SECS Message Language (SML)
SML is a general notation to describe individual SECS Data Items and complete SECS messages.
The format of a complete SECS message is:
SxFy W items.
The components are:
||The Stream and Function Codes (for example, S1F1).
The W-Bit, if set. Omitted if not set. If the W-Bit is optional, it is coded within brackets “[W]".
||Each message may contain any number of SECS-II Data Items. The Data Items are described using the format defined in the next section.
||A period (.) ends the message definition.
For example, the S1F1 message (which has no Data Items) can be represented as follows:
Data item format
For SECS messages that contain individual Data Items, the items portion of the SML description is used to define these Data Items. The format for describing a SECS-II Data Item in SML is as follows:
< type [ count ] value >
The components are:
Angle Brackets. Each Data Item is enclosed within angle brackets. This
notation implies that each Data Item has a Data Item Format and Data Item
Length as required by SECS-II.
The SECS-II Data Item type (Integer, ASCII, Binary, and so forth) is
represented by symbols in SML, but the SEMI standards documentation uses
an octal notation for the format code; the complete 8-bit code is usually
represented in the software in hexadecimal notation.
SECS Data Items
can vary in length from 0-7,995,144 bytes, so the number of Length Bytes
required to represent the total length ranges from 1-3 bytes. The standard
octal notation represents only the high-order 6-bits of the format code
byte. The low-order 2-bits determine the number of length bytes. So the
full 8-bits (hexadecimal value) of the format code byte represent both the
type of Data Item and the number of length bytes. Any given Data Item type
can be represented by 3 different hexadecimal values: 1 length byte (LB),
2-LB, and 3-LB. See Table 1: Notation Types for the relationship among these
different notation styles.
The array count of the element values that make up the item. If present,
the count is enclosed within square brackets “[ ]”. The
count may be omitted, in which case the square brackets are also omitted.
If count is omitted, then the length of the Data Item is
implied by the value that follows.
The count specifies
the number of value elements in the Data Item. For String formats (ASCII,
Binary, JIS-8), count specifies the number of characters
in the string. For Numeric formats (I1, I2, I4, I8, U1, U2, U4, U8, F4,
F8, BOOLEAN), count specifies the number of values in the
array. For simple scalar numeric values, count is usually
“1”. For LIST Items, count specifies the number of items
in the list.
Where count can range between known
limits, it can also be specified as minimum and maximum counts separated
by two dots. For example, a Data Item that is an array of ASCII characters
(a string) with a valid length of 1 to 8 characters can be represented as
The count specifier indicates the
number of value elements in the array, which is not necessarily the same
as the length of the Data Item.
The value of a single item element. Values are shown in a notation that
depends on the item type. For example, ASCII values are shown as characters
enclosed in quotes, Unspecified Binary values are shown in hexadecimal notation.
Numeric values shown for Integer Data Items are considered decimal Integers
unless otherwise indicated. Negative values are shown with a leading minus
sign “-”. Hexadecimal values are shown in C-Language convention, with a
Where a value is not fixed, the SECS data item name is used directly:
- 10 - Decimal Ten
- 0x10 - Hexadecimal 10
- -10 - Decimal Negative 10
Ellipsis (...) is used to indicate that additional elements may occur (for
example, where substructures may repeat in a List structure).
Table 1: notation types
|8-byte Signed Integer
|1-byte Signed Integer
|2-byte Signed Integer
|4-byte Signed Integer
|8-byte Unsigned Integer
|1-byte Unsigned Integer
|2-byte Unsigned Integer
|4-byte Unsigned Integer
Special notation rules
The following section describes the notation rules for SML, SECS Message Language.
ASCII Data Item values must be defined with double-quotes (“ ”). It is possible to have long values which would span multiple lines on a printed page. In this case, you would need to use double quotes around each line, for example:
It is also possible to add whitespace characters, such as carriage returns and linefeed characters. These special characters must be added in hexadecimal notation and cannot be included in quotes:
<A “XXXXXXXXXXXXXXXXX” 0x0A 0x0D “YYYYYYYYYY”>
Binary Data Item values are usually specified in hexadecimal notation and must be preceded by “0x”. For example, the value 16 in a Binary Data Item would be written as:
Lists do not contain values themselves; they contain other Data Items instead. Normally, separate Data Items within a list are displayed on separate lines. Each of the component Data Items is indented. The closing “>” character for the list Data Item is placed alone on a separate line at the same indentation level as the initial "<L".
It is also possible to have sub-lists embedded within lists. In this case, each sub-list is displayed on a separate level.
Data Items can have a length of zero. This simply means that the Data Item has no value and contains only a format code (1-byte) and 1 length byte (whose value is zero). Many SECS-II messages use zero-length items for special purposes. For example, the S1F3 Status Variable Request uses a zero-length List Item to indicate that all Status Variables are requested, instead of listing all the SVIDs separately.
A zero-length item is shown in SML using an open bracket “<“ and a close bracket “>”. Adding a zero count specifier “” is not required. Below are some examples of how a zero-length Data Item would be written in SML.
| 4-byte Int.
Combining the generic message formatting rules with the Data Item formatting rules, you can now use SML to completely describe any SECS message.
For example, the generic format for S5F1 (Alarm Report) would be described in SML as follows:
A specific S5F1 sent by the Equipment might be described in SML as follows:
<A "ON FIRE">