Somos: 5. SCP-SMS/800 USL Specification

This section describes a subset of the "OTGR: User System Interface - User System Language", hereafter referred to as USL, that is to be implemented for SCP-SMS/800 messages. The subset of USL to be implemented is the Input (command) Language with a binary data definition enhancement. Both commands and responses use this format.

 

The message format is common among the SCP, SMS/800, and STP systems, and the SEAS operations support system. For messages between SMS/800 and an SCP, some of the option blocks are not needed and will not be used for the Phase I release.

 

NOTE  SMS/800 does not have any communication to/from the STPs.

 

This section presents the highlights of the language and the features that are to be implemented for the definition of the messages between SMS/800 and an SCP. The user should refer to the above references for a description of the language and examples.

 

5.1  Language Specification

The following is the meta-language used for the description of the USL in this section:

"..."	to indicate a consecutive and inclusive string.
"| (vertical bar)"	alternatives (or).
"[ ]"	optional units.
"*"	to have zero or more repetitions.
"+"	to have one or more repetitions.
"( )"	to enclose a unit.
":="	is defined as

 

5.1.1  Character Set of Data Elements

The following are the allowable characters within each data element of USL. The character set is a subset of the 7-bit ASCII code. Characters not defined here are illegal in data elements, and character validation will be applied to all non-binary fields.

Digits

Digits are characters with octal values 060 to 071 that represents ASCII character 0 to 9, respectively.

DIGIT:= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

Letters

Letters are characters with octal values 101 to 132 that represents ASCII characters A to Z, respectively.

LETTER:= A |...|Z

Only use capital letters (ALL CAPS).  Do not use lower case letters.

Graphic Characters

Graphic characters are to be sent in octal values for the following supported ASCII characters:

GRAPHICS:= # | $ | % | & | ' | ( | ) | * | + | - | . | / | > | @

 

Summary of Key Characters

ASCII Character	Octal Value	Purpose of Character
(blank space)	040	A blank character can be used within a text string.
"	042	A quotation mark is used as a text string delimiter.
$	044	A dollar sign is used in binary data.
,	054	A comma is used as a separator for parameters within a block of parameters.
-	055	A hyphen is used as a separator for information units in command codes.
.	056	A period is used as a separator for the integer and fractional portion of a decimal number.
0 to 9	060 to 071	Represents a single numeric digit in the range of 0 through 9.  Octal value 061 represents the digit 1.
:	072	A colon is used as a separator which precedes each block of parameters.
;	073	A semicolon is used as an indicator for terminating a command.
=	075	An equals sign is used as a separator between a parameter name and its value.
A through Z	101 to 132	Represents a single letter in the range of A through Z.  For instance, octal value 101 represents the letter A, and octal value 132 represents the letter Z.

 

5.1.2  Data Elements

Identifier

An IDENTIFIER is a string of one to ten characters which begins with a letter, followed by digits and/or letters.

IDENTIFIER := letter(digit | letter)*

For example: RSP

 

Decimal Numeral

DECIMAL NUMERAL data elements are interpreted as decimal digits (see section 5.1.1). A decimal numeral consists of one or more digits (0 through 9).  Do not use binary to represent decimal numerals.

DECIMAL NUMBER := (digit)+

For example: 10

The following is an example of sending, to or from SMS/800, error code value ASCII "08" in the Error_cd field of a message when the Error_cd field is defined as decimal number or decimal: In this example, the Error_cd field needs to be populated with octal 060 in byte 1

of the Error_cd field and populated with octal 070 in byte 2 of the Error_cd field, and that is because 060 octal = ASCII 0, and 070 octal = ASCII 08.

 

Text String

TEXT STRING data elements are zero or more characters encapsulated (enclosed) within two quotation marks (“), one quotation mark at the beginning of the text string and a quotation mark at the end of the text string.

TEXT STRING:= "(letter | digit | graphics | blank)*"

For example: "ABC$#"

Here is an example of an empty text string (two quotation marks and a blank space): " "

 

Binary Data

BINARY DATA items are used to transfer binary strings. Binary data are byte oriented. Each binary unit is 8 bits long. They are not checked for illegal characters. Bit count starts from right to left, where bit 0 is the right-most bit position. Bit 7 is the most significant bit. Bit 0 the least significant bit.

In binary data strings, the data is sent with the most significant byte first and the least significant byte last.

BINARY DATA := $(integer)(bin_data)

 

WHERE:
integer	is a positive signed binary number 4 bytes long and each byte has 8 bits. This number indicates the number of bytes in 'bin_data'.
bin_data	contains the binary data string where each byte is eight bits long.

 

The internal representation of a one byte binary data definition of the bit pattern

00000001 in hex:

240000000101
WHERE
24	byte 0 is the ASCII character $ (24 in hex).
00000001	bytes 1 to 4 are the internal representation of the integer 1 (01 in hex).
01	byte 5 is the bit pattern 00000001 (01 in hex).

 

The internal representation of a two byte binary data definition of the bit pattern

1111111111111111 in hex :

2400000002FFFF
WHERE:
24	byte 0 is the ASCII character $ (24 in hex).
00000002	bytes 1 to 4 are the internal representation of the integer 2 (00000002 in hex).
FFFF	bytes 5 and 6 are the bit pattern 1111111111111111 (FFFF in hex representation).

 

5.1.3  Commands and Reply Messages

Commands and replies have the same syntax in this USL subset for SCP and SMS/800 messages. Parameters in a parameter block are parameter-named (i.e., keyed), except for parameters in the first five blocks. The first five blocks use positional defined parameters, and are considered header data. Positional-defined parameter option is not used for any subsequent parameter blocks for SCP and SMS/800 messages.

• SYNTAX

command syntax := command[:parameter block]*;

 

• COMMAND

command := identifier[-identifier[-identifier]]

Note: The first identifier is the USL command verb listed in Section 6.

 

• PARAMETER BLOCK

parameter block :=

(parameter-name defined parameter

(,parameter-name defined parameter)*)

 

parameter-name defined parameter :=

parameter_name=parameter_value

 

• PARAMETER NAME

parameter_name :=

identifier

 

• PARAMETER VALUE

parameter_value :=

simple parameter argument

 

• SIMPLE PARAMETER ARGUMENT

simple parameter argument :=

information_unit

 

• INFORMATION UNIT

information_unit :=

identifier | decimal numeral | text string | binary data

 

5.2  SCP-SMS/800 Message Formats

The SCP, SMS/800, and STP software systems, and the SEAS operations support system, have a common message format for messages. For the messages between SMS/800 and an SCP, some of the optional header blocks are not needed and will not be used for early releases. Optional header blocks not used are indicated by a colon with no parameters following it, as illustrated in the following format definitions.

 

5.2.1  Command Format

For messages from SMS/800 to an SCP, which are defined as input command messages, the following format is used:

verb-mod:::::[:message specific data block]*;

WHERE:

 

verb :	input MM command verb as defined in Section 6. Maximum of 10 characters/verb.
mod :	the individual message id. Maximum of 10 characters/modifier.
message specific data block :	keyed block, maximum of 50 keys per block, maximum of 200 blocks per message. Maximum of 10 characters/key.

 

5.2.2  Response Format

For response messages from the SCP, the following format is used:

verb-mod:,date,time:::status:[:message specific data block(s)]*;

WHERE:

 

verb :=	Response USL command verb as defined in Section 6.  Maximum of 10 characters/verb.
mod :=	The individual message id. Maximum of 10 characters/modifier.
date :=	Year-MONTH-day (with dashes in date field)   in the format: YYYY-MM-DD
	Year := digit digit digit digit (e.g., 2007)
	MONTH := digit digit (range 01 to 12)
	Day := digit digit (range 01 to 31)
time :=	Hour-minute-second-zone (with dashes)   in the format: HH-MM-SS-ZZZ
	Hour := digit digit (range 00 to 23)
	Minute := digit digit (range 00 to 59)
	Second := digit digit (range 00 to 59)
	Zone := time zone of sending site   (NST, NDT, AST, ADT, EST, EDT, CST, CDT, MST, MDT, PST, PDT, YST, YDT, HST, HDT, BST)
status :=	term_rept,error_cd
	term_rept := one of the following:
	COMPLD - message request completed.
	DENIED - message request denied.
	error_cd := message specific error code as defined for each message. Should be 00 if term_rept is COMPLD. Should be 01 for syntax errors.
	Other error codes are message specific. (maximum of 4 alphanumeric characters)
message specific data block :	Keyed block, maximum of 50 keys per block, maximum of 200 blocks per message. Maximum of 10 characters/key.

 

5.2.3  Unsolicited Response Format

For unsolicited messages from the SCP, the following format is used:

verb-mod:,date,time::::[:message specific data block(s)]*;

WHERE:

verb :	unsolicited message USL command verb as defined in Section 6. Maximum of 10 characters/verb.
mod :	the individual message id, as defined above for response messages.
date :	= as above for response messages.
time :	= as above for response messages.
message specific data block :	as above for response messages.

 

5.2.4 Data Block Format

Repeating data structures should be used in a data block whenever multiple values are assigned to an array of variables. More than one structure may repeat in a block.

 

Keys may not be repeated in a data block. Keyed data structures that repeat in a data block must use different keys for each instance of the data. If the same key words are desired, each instance of data may be placed in different data blocks with keys repeated from one block to the next.

 

Data structures that repeat in a block must have a count field of the number of repeating instances of the data. The count field must precede the first occurrence of the repeating structure.

 

5.3  MESSAGE SPECIFICATIONS

The following sections describe the overall message format and conventions for the messages that carry information from SMS/800 to the SCP application and from the SCP application to SMS/800. Each message must follow the conventions and format described in the following sections.

 

Both CMSDB-SMS/800 messages as well as SCP Node-SMS/800 messages share the same message conventions and general formats.

 

NOTE  From each SCP, there must be four socket connections to SMS/800 (two to each of the two Data Communication Manager servers). Of the two connections to each SMS/800 DCM, one connection is for Node message and one connection is for CMSDB message.

 

5.3.1   MESSAGE PAGE DOCUMENT CONVENTIONS

The message manual uses the following convention in the definition of the messages.

 

Upper case:               These are characters or words that are part of the actual message definition

Lower case:               These are characters or words that describe the content of that parameter.

 

5.3.2   MESSAGE PAGE DESCRIPTION

Each message is described on a separate message page in Section 7. A message page contains the following:

• The message name and its acronym.
• A brief description of the message.
• The message format for that message.
• The description of each of the parameters in the message.
• The data types for each value of a parameter (identifier, decimal numeral, text string, binary data). Note: text implies quotes enclose the data, and binary implies a $ sign followed by a byte count precede the data.
• The maximum message length for this message (includes any data type identifiers, such as quotes for text strings or$ followed by a byte count for binary data).
• The frequency that this message is issued.

 

5.4  Message Conventions

5.4.1  Validation

The following message processing rules should be followed:

1. Do not make assumptions regarding the sequence of keyword (i.e. parameters with names) parameters in any messag
2. Unknown keyword parameters (not defined in this document) should be ignored by the receiver of the mess
3. If a required keyword parameter is missing, the receiver of the message should send a response message containing a termination report ("term-rept" parameter) of "DENIED" if applicable.

The Message Format portion of each message description in Section 7 (CMSDB-SMS/800 MESSAGES) specifies which parameters are optional where appropriate. If this is not specified for a given field, assume that the parameter is required.

 

5.4.2  Confirmation

In general, commands sent from SMS/800 require application-to-application level confirmation. Responses from the SCP contain a date and time stamp, as indicated in Section 5. This specifies the date and time the message is sent. For certain responses from the SCP, the data in the message must also be time stamped. When this is the case, the convention used is elapsed seconds from January 1, 1970, in the time zone of the sender (as specified in Section 5).

 

Characters are stored in ASCII on the SCP side and stored as EBCDIC on the SMS/800 side. It is the responsibility of each SMS/800 application program to convert its own data (non-binary) from EBCDIC to ASCII for messages going out to an SCP and from ASCII to EBCDIC for messages coming from an SCP.

 

From a data maintenance and control perspective, update messages are divided into two types. The first type are those where data files are maintained only by the SCP, and records/ fields in these files are updated by messages from SMS. Retrieve messages are sent by SMS, when necessary, to obtain complete copies of the SCP files. Few of the update messages are of this type.

 

The following update messages, which appear in Section 7, are of this first type:

ENT-MCL, DLT-MCL

ENT-SSL, DLT-SSL

 

The second type are those where the SCP and SMS/800 both maintain copies of data files (e.g. customer data), and messages are used to keep both files in synchronization. For these data files, any local SCP updates will be overwritten by a subsequent update message from SMS. The following update messages, which also appear in Section 7, are of the second type:

 

•  UPD-ALP
	•  UPD-MNL
	•  UPD-NMP
•  UPD-CCO
•  UPD-DTT	•  UPD-UCR
•  UPD-ETT

 

5.5  TCP/IP Parameters

See SR-4959 for a discussion of TCP/IP application messages required to be supported for SMS/800 (listed below) and TCP/IP parameters.

 

Each SCP is required to support the following TCP/IP message type for the SMS/800-SCP interface:

• Good Day = message code 01
• Good Night = message code 05
• Good Bye (Disconnect Request) = message code 06
• Error = message code 09
• Data (UPL Header/UPL Message Data) = message code 19.