Grammar


Type:	String of C type T_STR
Default Value:	None. This value must be supplied when creating a message type.
Valid Values:	Any valid field type or types (as shown in Table 1 and Table 2)

The grammar property identifies the layout of fields in messages that use this type. The grammar consists of a list of field types. Each field type in the grammar corresponds to one field in the message. For example, the standard message type TIME has a grammar real8, which defines the first and only field as being an eight-byte real number. Standard Message Types lists the grammars of all standard message types. Comments (delimited by /* */ or (* *)) are also allowed in the grammar.

if (!TipcMtGetGrammar(mt, &grammar)) { 
  /* error */ 
}

The main purpose of the grammar is to allow messages to be written to text files in a more compact format (see Message Files for information on message files). Without a message type grammar, it is difficult to know if the number 45 in a text message file was an INT2, INT4, INT8, REAL4, REAL8, or REAL16 field. Message type grammars also provide some self-documentation for message types. The grammar is not enforced, however, when a message is constructed. A message type with a grammar STR REAL8, for example, does not stop a message from being constructed with ten INT4 fields.

Message type grammars do not have any relationship to the data conversion capabilities of connections described in Sending Messages in a Heterogeneous Environment. SmartSockets messages have strongly-typed fields. The field types, not the grammar, enable connections to perform byte swapping and floating-point conversions.

In addition to the field types shown in Table 1, the field types in Table 2 can be used when defining a message type grammar. They allow values to print in a more readable form when written to a message file.

Table 2 Pseudo Field Types for Message Type Grammar
Field Type	Purpose
ID	Use for the STR field type when the value should be printed without quotes. This is useful for identifiers.
VERBOSE	Use for any field type when both the field type and value should be printed. For example, instead of values printing as `voltage 33.4534`, they would be printed as `str "voltage" real8 33.4534`.

There are two common uses for the pseudo field type verbose in message type grammars. The most common usage is when the layout of the fields varies (for example, the type of the second field in the message depends on the value of the first field). The verbose type can also be used when you don’t want to use a well-defined grammar. If verbose is used in a message type grammar, it has to be the only field type in the grammar (for example, "str verbose" and "verbose real8 str" are not valid grammars).

Occasionally, message types use a repetitive group of fields. For example, the NUMERIC_DATA message type allows zero or more name-value pairs. Curly braces ({}) may be used in the message type grammar to indicate such a group. The grammar for the NUMERIC_DATA message type is "{ id real8 }" and the grammar for HISTORY_STRING_DATA is "real8 { id str }". Groups must be at the end of the message type grammar, and only one group is allowed for each grammar.