26.2. Using the +CMGR AT Command to Read an SMS Message from a Message Storage Area

The AT command +CMGR (command name in text: Read Message) is used to read a message from a message storage area. The location of the message to be read from the message storage area is specified by an index number. The message to be retrieved by the AT command +CMGR does not necessarily have to be an SMS message. It can be of other message types such as status reports and cell broadcast messages, but we will only focus on SMS messages here.

In SMS text mode, you can retrieve the following information about an SMS message with the AT command +CMGR:

In SMS PDU mode, the list becomes:

After using the +CMGR AT command to read an SMS message with the "received unread" status, the status will be changed to "received read".

The message storage area from which SMS messages are read is specified by the +CPMS AT command (command name in text: Preferred Message Storage). Details about the +CPMS AT command can be found in the earlier section "Preferred Message Storage (AT+CPMS)" of this SMS tutorial.


26.2.1. Syntax of the +CMGR AT Command in SMS Text Mode

The syntax of the +CMGR AT command in SMS text mode is:


+CMGR=index


index is an integer specifying the location of the SMS message to be read from the message storage area.


26.2.2. Format of the Information Response of the +CMGR AT Command in SMS Text Mode

If the GSM/GPRS modem or mobile phone successfully reads the SMS message from message storage, it will return an information response to the computer / PC. In SMS text mode, the format of the information response of the +CMGR AT command is different for different message types. In the sections that follow, we assume the message to be read is an SMS message but not of other message types like status reports and cell broadcast messages.


26.2.2.1. Incoming SMS Messages and Outgoing SMS Messages

If the SMS message retrieved is an SMS message received from the SMS center (i.e. incoming SMS message), the information response of the +CMGR AT command in SMS text mode has the following format: (Optional fields are enclosed in square brackets.)


+CMGR: message_status,address,[address_text],service_center_time_stamp[,address_type,TPDU_first_octet,protocol_identifier,data_coding_scheme,service_center_address,service_center_address_type,sms_message_body_length]<CR><LF>sms_message_body


If the SMS message retrieved is an SMS message that you wrote to the message storage area for sending out (i.e. outgoing SMS message), the format is: (Optional fields are enclosed in square brackets.)


+CMGR: message_status,address,[address_text][,address_type,TPDU_first_octet,protocol_identifier,data_coding_scheme,[validity_period],service_center_address,service_center_address_type,sms_message_body_length]<CR><LF>sms_message_body


As you can see above, the format of the +CMGR information response for incoming SMS messages and for outgoing SMS messages is slightly different. The differences are:

Before we discuss each of the fields that appear in the +CMGR information response, let's see two examples that give you some idea of how an actual +CMGR information response should look like:


For incoming SMS messages:

+CMGR: "REC READ","+85291234567",,"07/04/20,10:08:02+32",145,4,0,0,"+85290000000",145,49
It is easy to read text messages via AT commands.


For outgoing SMS messages:

+CMGR: "STO SENT","+85291234567",,145,17,0,0,167,"+85290000000",145,36
A simple demo of SMS text messaging.


26.2.2.2. Details of the Fields that Appear in the +CMGR Information Response


The message_status Field

The first field of the information response of the +CMGR AT command, message_status, is a string that indicates the status of the SMS message. It can be one of the following four values:


The address Field

The second field of the information response of the +CMGR AT command, address, is a string that contains the address/phone number stored in the SMS message header. If the SMS message read is an incoming SMS message, the address field contains the originator address. If the SMS message read is an outgoing SMS message, the address field contains the recipient address. Usually the address field value is a phone number formatted using the typical ISDN / telephony numbering plan (ITU E.164/E.163). For example, "+85291234567".


The address_text Field

The third field of the information response of the +CMGR AT command, address_text, is a string that contains the text associated to address in the phonebook. For example, if the text "Alice" is associated to the phone number "91234567" in the phonebook, address_text will be "Alice". The AT command +CSCS (command name in text: Select TE Character Set) can be used to specify the character set for displaying address_text. Note that address_text is an optional field. Some GSM/GPRS modems and mobile phones (examples: most Nokia products, including my Nokia 6021) leave this field empty.


The service_center_time_stamp Field

The fourth field of the +CMGR information response for incoming SMS messages, service_center_time_stamp, is a string that contains the time and date at which the SMS message arrived at the service center (i.e. SMSC). The time stamp format is "yy/MM/dd,hh:mm:ss±zz" (yy = year, MM = month, dd = day, hh = hour, mm = minute, ss = second, zz = time zone [Note: the unit of time zone is a quarter of an hour]). For example, "07/02/05,08:30:45+32" represents 5 February 2007, 8:30:45 GMT+8 hours. (+32 means GMT+8 hours, since 32 quarters of an hour = 8 hours.)

Note that service_center_time_stamp is an optional field. This field is available to incoming SMS messages but not to outgoing SMS messages since outgoing SMS messages have not gone through an SMSC.


The address_type Field

The fifth (fourth) field of the +CMGR information response for incoming SMS messages (outgoing SMS messages), address_type, is an integer that indicates the type of the address contained in the address field. Usually it is one of the following two values:

Note that address_type is an optional field and it is not shown by default. The AT command +CSDH (command name in text: Show Text Mode Parameters) can be used to control whether the field address_type will be shown in the information response of the +CMGR AT command.


The TPDU_first_octet Field

The sixth (fifth) field of the +CMGR information response for incoming SMS messages (outgoing SMS messages), TPDU_first_octet, contains the first octet (expressed as an integer) of the TPDU of the SMS message.

Note that TPDU_first_octet is an optional field and it is not shown by default. The AT command +CSDH (command name in text: Show Text Mode Parameters) can be used to control whether the field TPDU_first_octet will be shown in the information response of the +CMGR AT command.


The protocol_identifier Field

The seventh (sixth) field of the +CMGR information response for incoming SMS messages (outgoing SMS messages), protocol_identifier, contains the value (expressed as an integer) of the TP-Protocol-Identifier parameter in the TPDU of the SMS message.

Note that protocol_identifier is an optional field and it is not shown by default. The AT command +CSDH (command name in text: Show Text Mode Parameters) can be used to control whether the field protocol_identifier will be shown in the information response of the +CMGR AT command.


The data_coding_scheme Field

The eighth (seventh) field of the +CMGR information response for incoming SMS messages (outgoing SMS messages), data_coding_scheme, contains the value (expressed as an integer) of the TP-Data-Coding-Scheme parameter in the TPDU of the SMS message.

Note that data_coding_scheme is an optional field and it is not shown by default. The AT command +CSDH (command name in text: Show Text Mode Parameters) can be used to control whether the field data_coding_scheme will be shown in the information response of the +CMGR AT command.


The validity_period Field

The eighth field of the +CMGR information response for outgoing SMS messages, validity_period, contains the validity period assigned to the SMS message. There are three possible validity period formats: relative format, absolute format and enhanced format. To find out the format of validity_period, examine the value of the TP-Validity-Period-Format parameter in the TPDU of the SMS message. It is located at bit 4 and bit 3 of the first octet of the TPDU. (Note: Bit 0 is the rightmost bit.) For example, let's say the value of the TPDU_first_octet Field is 17. Its binary representation is 00010001. As you can see, bit 4 is 1 and bit 3 is 0.

If the relative format is used (bit 4 = 1, bit 3 = 0), validity_period will be an integer in the range from 0 to 255 that indicates the period after which the SMSC should delete the SMS message, counted from the time at which the SMSC receives the SMS message. The validity period can be calculated by the following formulae:

If the absolute format is used (bit 4 = 1, bit 3 =1), validity_period will be a string that contains the time and date at which the SMSC should delete the SMS message. The time/date format is "yy/MM/dd,hh:mm:ss±zz" (yy = year, MM = month, dd = day, hh = hour, mm = minute, ss = second, zz = time zone [Note: the unit of time zone is a quarter of an hour]). For example, "07/02/05,08:30:45+32" represents 5 February 2007, 8:30:45 GMT+8 hours. (+32 means GMT+8 hours, since 32 quarters of an hour = 8 hours.)

If the enhanced format is used (bit 4 = 0, bit 3 = 1), validity_period will be a hexadecimal coded string. Since the enhanced format is not commonly used, we do not discuss the details here.

Note that validity_period is an optional field and it is not shown by default. The AT command +CSDH (command name in text: Show Text Mode Parameters) can be used to control whether the field validity_period will be shown in the information response of the +CMGR AT command. Also, note that validity_period is available to outgoing SMS messages but not to incoming SMS messages, since there is no such value stored in the headers of incoming SMS messages.


The service_center_address Field

The ninth field of the information response of the +CMGR AT command, service_center_address, is a string that contains the SMSC address stored with the SMS message. Usually it is a phone number formatted using the typical ISDN / telephony numbering plan (ITU E.164/E.163). For example, "+85291234567".

Note that service_center_address is an optional field and it is not shown by default. The AT command +CSDH (command name in text: Show Text Mode Parameters) can be used to control whether the field service_center_address will be shown in the information response of the +CMGR AT command.


The service_center_address_type Field

The tenth field of the information response of the +CMGR AT command, service_center_address_type, is an integer that indicates the type of the SMSC address contained in the service_center_address field. Usually it is one of the following two values:

Note that service_center_address_type is an optional field and it is not shown by default. The AT command +CSDH (command name in text: Show Text Mode Parameters) can be used to control whether the field service_center_address_type will be shown in the information response of the +CMGR AT command.


The sms_message_body_length Field

The eleventh field of the information response of the +CMGR AT command, sms_message_body_length, is an integer that indicates the number of characters contained in the sms_message_body field. For example, there are 48 characters in "It is easy to read text messages via AT commands". If the value of the sms_message_body field is "It is easy to read text messages via AT commands", the value of the sms_message_body_length field will be 48.

Note that sms_message_body_length is an optional field and it is not shown by default. The AT command +CSDH (command name in text: Show Text Mode Parameters) can be used to control whether the field sms_message_body_length will be shown in the information response of the +CMGR AT command.


The sms_message_body Field

The twelfth field of the information response of the +CMGR AT command, sms_message_body, contains the body of the SMS message.


Previous Page Page 56 of 65 Next Page

Contents at a Glance (Click Here for Full Table of Contents)

A button for going back to the top of this page