BUFFER


>>-BUFFER--=--+-buffer_address------------------+--------------><
              +-(--buffer_address--,--LUNAME--)-+   
              '-(--buffer_address--,--SCAN--)---'

macroinstructions:

USSMSG

dependencies:

TEXT, OPT, SUPP, terminal operator messages

buffer_address

Specifies the address (name) of an area of storage defined to contain the message text and a header indicating the length of the message text. The storage area must be formatted as shown in Figure 1.

Figure 1. USS message layout in storage

The message text defined in the storage area must follow the rules listed in Syntax rules for messages.

The message text is sent to the terminal operator as it appears in the storage area. VTAM® does not modify or translate the message text (even if FEATUR2=LOWERCSE is specified for the device). You are responsible for including any device-dependent control characters within the message.

LUNAME|SCAN

Specifies that the character strings listed in Table 1, will be replaced with the appropriate values in the position in the message where the character string occurred. The entire string specified by BUFFER will be searched, using the character @.

For example, if the following data was in the message text storage area

'@@LUNAME IS NOW IN SESSION WITH VTAM, @@@@DATE'

the message received at the terminal would look like the following information:

'TERMA    IS NOW IN SESSION WITH VTAM, 01/04/94'

Note: For terminals with large screen sizes, searching the storage area for a character string might be a performance consideration.

Table 1. Valid character strings for message definition
Character string	In message text	Format
@@@@DATE	Current Date	In the format and with the delimiter specified in the DATEFRM and DATEDLM operands on the USSTAB macroinstruction.
@HOSTNET	NETID from Start Options	The network ID is left-aligned and trailing blanks are inserted, if the network ID is fewer than eight characters.
@...@ZONEID	Client IPv6 zone ID	If the IPv6 zone ID exists, it will be included.
@...@IPADD	Client IP Address	39 bytes, leading zeros suppressed, left justified, with trailing blanks if needed. If the IP address type is IPv4 then it will be in dotted-decimal format. If the IP address type is IPv6 it will be in colon–hexadecimal format.
@...@IPHOSTNAME*	DNS Name of client	Name left justified with trailing blanks if fewer than 40 characters in length.
@@LUNAME	Terminal name	The name is left-aligned and trailing blanks are inserted, if the name is fewer than eight characters.
@@@NETID	Network ID	The network ID is left-aligned and trailing blanks are inserted, if the network ID is fewer than eight characters. The network identifier for a nonnative-network-attached terminal is the real network name (the network identifier of the network where the terminal resides), not the name of the network it is attached to.
@@@@@@@@@@@@@@NQN	Network-qualified name	The network-qualified name is left-aligned and trailing blanks are inserted if the network-qualified name is fewer than 17 characters, as networkID.name.
@@PRT	Client Port Address	Five bytes and leading zeros are not suppressed.
@@@@RUNAME	Request/response unit	The name of the request or response unit is left-aligned and trailing blanks are inserted, if the RU name is less than ten characters. Applies only to USSMSG07 when coded using the BUFFER operand.
@@@SENSE	Sense code	Eight-character sense code. Applies only to USSMSG07 when coded using the BUFFER operand.
@@SSCPNM	SSCPNAME from Start Options	The SSCP name is left-aligned and trailing blanks are inserted, if the SSCP name is fewer than 8 characters.
@@@@TIME	Current Time	As HH_MM_SS, where an underscore (_) is the delimiter specified on the TIMEDLM operand of the USSTAB macroinstruction.

*IPHOSTNAME must be preceded by 40 @ symbols.

Note:

Although a message size of 65535 (X'FFFF') can be specified, ensure that the terminal can support the size of the message specified.
BUFFER and TEXT are mutually exclusive. VTAM produces an error message if both the BUFFER and TEXT operands are coded.
If start option IPINFO=NONE or IPINFO=DISPONLY is in effect, then the client IP address and DS name of client will not be available for substitution even if they were given to VTAM by the LU.
If you code either the OPT or SUPP operands in addition to BUFFER, the OPT or SUPP operand will be ignored.
Various ABENDs can occur during USS processing if the USS table is improperly constructed. This is typically a user error because the USS table was incorrectly defined or modified.
ABEND0C4 can occur in the following modules:
- ISTINCF1
- ISTUSCMG
ABEND0A9 RCFF18 can occur in module ISTSSCCU. The most common user error occurs when the USS message is defined using the BUFFER=operand (instead of the TEXT=operand). When defining a USS message using BUFFER=, the message buffer must be constructed as follows:
- USS Message length (2 bytes)
- USS Message text (up to 65535 bytes)
The USS message length field contains the length of the USS message text only (do not include the length of the 2-byte length field in the calculation of the message length).

The following assembler statements show a popular method which can be used to define a USS message and the corresponding buffer when the BUFFER= operand is used:
Somewhere after the USSTAB macro, code the USSMSG macro for the message you wish to define (this example uses USSMSG10):
- USSMSG MSG=10,BUFFER=(MSG10)
Later, usually after the USSEND macro, define the USS message buffer as follows:
```
MSG10       DC  AL2(MSG10E-MSG10S)    * Msg length (2 byte field)       
 MSG10S   EQU *                     * Start of USS message            
                      DC  C'Place up to 65535 bytes of USS message text here'     
 MSG10E   EQU *                     * End of USS message 
```
Note: The BUFFER= operand specifies the location of the 2-byte length field which is immediately followed by the message text.