26.3. Using the +CMGL AT Command to List SMS Messages of a Certain Status from a Message Storage Area

The AT command +CMGL (command name in text: List Messages) is used to list messages of a certain status (for example, "received unread" and "received read") from a message storage area. The messages listed by the AT command +CMGL do not necessarily have to be SMS messages. They 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 +CMGL:

In SMS PDU mode, the list becomes:

If the status of a message is "received unread", after being retrieved by the +CMGL AT command, the status is 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.3.1. Syntax of the +CMGL AT Command in SMS Text Mode

The syntax of the +CMGL AT command in SMS text mode is: (Optional parameter is enclosed in square brackets.)


+CMGL[=message_status]


The message_status parameter takes a string that specifies the message status to be used to find messages to return. The SMS specification has defined five message status values, which are shown below. You can perform a test operation to find the actual values supported by your GSM/GPRS modem or mobile phone. See the "Finding the Message Status Values Supported by the +CMGL AT Command in SMS Text Mode" section for the details. Usually all five status values are supported.

For example, if "REC READ" is specified to the message_status parameter, the +CMGL AT command will list all messages that have the "received read" status from the message storage area.

Note that message_status is an optional parameter. If it is omitted, the +CMGL AT command will use the default value "REC UNREAD".


26.3.2. Format of the Information Response of the +CMGL AT Command in SMS Text Mode

If the GSM/GPRS modem or mobile phone reads the SMS messages from message storage successfully, it will return an information response to the computer / PC. Suppose the messages to be listed are SMS messages (not of other message types like status reports and cell broadcast messages), the information response of the +CMGL AT command in SMS text mode has the following format: (Optional fields are enclosed in square brackets.)


+CMGL: index,message_status,address,[address_text],[service_center_time_stamp][,address_type,sms_message_body_length]<CR><LF>sms_message_body[<CR><LF>+CMGL: ...]


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


+CMGL: 1,"REC READ","+85291234567",,"07/05/01,08:00:15+32",145,37
It is easy to list SMS text messages.


The index Field

The first field of the information response of the +CMGL AT command, index, is an integer that specifies the location of the SMS message in the message storage area.


The message_status Field

The second field of the information response of the +CMGL 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 third field of the information response of the +CMGL 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 fourth field of the information response of the +CMGL 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 fifth field of the information response of the +CMGL AT command, 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 sixth field of the information response of the +CMGL AT command, 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 +CMGL AT command.


The sms_message_body_length Field

The seventh field of the information response of the +CMGL 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 36 characters in "It is easy to list SMS text messages". If the value of the sms_message_body field is "It is easy to list SMS text messages", the value of the sms_message_body_length field will be 36.

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 +CMGL AT command.


The sms_message_body Field

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


Multiple SMS Messages in the Information Response

If there are multiple SMS messages to be returned, the information response of the +CMGL AT command will contain more than one "+CMGL: ...". Two characters, <CR><LF>, are used to delimit two "+CMGL: ...". Here is an example for illustration. Suppose the command line 'AT+CMGL="ALL"' is executed and three SMS messages are listed. If all characters are shown, the command line and the response returned will be displayed like this:


AT+CMGL="ALL"<CR>
<CR><LF>+CMGL: ...<CR><LF>+CMGL: ...<CR><LF>+CMGL: ...<CR><LF>
<CR><LF>OK<CR><LF>


In a terminal program such as HyperTerminal of Microsoft Windows, a carriage return character causes the cursor to be moved to the beginning of the current line, and a linefeed character causes the cursor to be moved to the same position on the next line. Hence, the above result will be displayed like this in a terminal program such as HyperTerminal of Microsoft Windows:


AT+CMGL="ALL"
+CMGL: ...
+CMGL: ...
+CMGL: ...

OK


Previous Page Page 60 of 65 Next Page

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

Feedback Form (ExpandCollapse)

What do you think about this web page?






(Optional) Please provide us more details. For example, suppose you select option 2 above, can you tell us specifically what information is missing? You can also suggest anything that can help us improve this web page.

(Optional) Your name:

(Optional) Your email address:

Please enter again to confirm:

Due to the amount of messages we received, we may not be able to reply to all messages.