Syntax rules for messages

When preparing USS messages to be sent to a terminal operator, to a VTAM® operator, or to a program operator, the following rules apply:

Single quotation marks in the message text must be specified as in the assembler DC statement for character (C-type) constants.
The message text must conform to the rules for coding an assembler DC statement for character (C-type) constants. Alternatively, if noncharacter message text is required, the TEXT operand can be specified as a sublist, with each entry coded as the full operand of an assembler DC statement. If the sublist form is used, the assembler does boundary alignment processing. For example,
```
TEXT=(A(0),C'SAMPLE MESSAGE')
```
might result in some leading zeroes being supplied by the assembler to ensure that the "A(0)" part of the text is located on a fullword boundary. This could be avoided by specifying
```
TEXT=(AL4(0),C'SAMPLE MESSAGE')
```
If the message text contains blanks (X'40'), OPT=BLKSUP should not be specified for this message, because VTAM might delete some of the X'40' characters (unless that is what you want).
You cannot use the 3270 control commands and orders when creating USS messages for SNA devices. For further information, see the component description manual for the appropriate control unit and attached devices.
When VTAM issues a message, it can supply one or more variable data character strings to be inserted in the message text. The location of the variable data character strings in the message text is indicated by numbered or unnumbered percent signs (%).
- Numbered percent signs are used when a message has more than one variable character string. The first variable data string is represented by %(1), the second string by %(2), and so on, for as many strings as are provided by VTAM.
- An unnumbered percent sign is the same as specifying %(1).
You can rearrange the order of the percent signs in a message to change the order of the variable data in a message.
For example, if the message definition for IST380I:
```
TEXT='ERROR FOR ID = %(1) — REQUEST: %(2), SENSE: %(3)'
```
results in the message
```
ERROR FOR ID = NODE1234 — REQUEST: CDINIT, SENSE: 087D0001
```
Then this message definition for IST380I:
```
TEXT='%(2) REQUEST RECEIVED SENSE %(3) FOR NODE %'
```
results in the message
```
CDINIT REQUEST RECEIVED SENSE 087D0001 FOR NODE NODE1234
```
Note: Noncharacter data should not contain percent signs (X'6C') because VTAM interprets a percent sign as a point at which to insert variable data into the message.

Variable text can be used more than once in the same message or can be omitted in the redefined message.

TEXT='ERROR FOR ID = %(1) — REQUEST: %(2), SENSE: %(3)—%(2)'

would result in the message

ERROR FOR ID = NODE1234 — REQUEST: CDINIT, SENSE: 087D0001—CDINIT

If the number of a percent sign is greater than the number of variable data character strings provided for that message, that percent sign is replaced by the last available variable data.
For example, if %(7) were specified for the following message, the values for %(3) will be used.
```
TEXT='ERROR FOR ID = %(1) — REQUEST: %(2), SENSE: %(3)'
```
z/OS Communications Server: SNA Messages shows the number and location of the variable data character strings in each VTAM message. It also provides a message explanation that includes a description of what type of data can appear in each character string.
The maximum length of a message after replacement of any percent signs is 251 characters. If a message exceeds 251 characters, the USS table will not assemble. The maximum limit for messages in a message group is 60 characters for each message. Message will be truncated if maximum is exceeded.
Do not change the message ID that appears in the text of a VTAM operator message. If you do, you could affect IBM®'s ability to service your product.
The following characters can be used for USS messages:
- 26 uppercase and lowercase letters: A–Z, a–z
- 3 national characters: $ # @
- 10 numerical digits: 0–9
- All graphic characters greater than or equal to X'40' (with the exception of X'6C' which is the percent sign)
National characters (and any graphic or control characters not listed above) are sent to a terminal user only if present in user-specified message replacements specified through the BUFFER operand of the USSMSG macroinstruction.

Note: (For terminal operator messages only.) Because control characters are device-dependent, you should not include them in the data defined by the TEXT or BUFFER operands, unless you can select the appropriate character for the device to which the message will be sent. You may use the percent sign and blanks in data defined by the BUFFER operand. However, do not include the percent sign or blanks in the TEXT operand data because USS treats them differently.