BUFFER
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.
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
the message received at the terminal would look like the following information:'@@LUNAME IS NOW IN SESSION WITH VTAM, @@@@DATE'
'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.
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.
- 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.