USSMSG macroinstruction

Use the USSMSG macroinstruction to define Telnet terminal operator messages (USSMSGxx).

Syntax


>>-+------+--USSMSG--------------------------------------------->
   '-name-'           

>--+-BUFFER=--+-buffer_address------------+------+-------------->
   |          +-(buffer_address,--LUNAME)-+      |   
   |          '-(buffer_address,--SCAN)---'      |   
   |                      .-OPT=BLKSUP---------. |   
   '-TEXT='MESSAGE_TEXT'--+--------------------+-'   
                          |       .-BLKSUP---. |     
                          '-OPT=--+----------+-'     
                                  '-NOBLKSUP-'       

>--MSG=--+-message_id-----------+------------------------------><
         |    .-,----------.    |   
         |    V            |    |   
         '-(----message_id-+--)-'

Parameters

name

Specifies the name assigned to the macroinstruction.

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

A USS message consists of a 2-byte header and m-byte message text.

The message text defined in the storage area must follow the USSEND macroinstruction.

The message text is sent to the terminal operator as it appears in the storage area. Telnet does not modify or translate the message text. You are responsible for including any device-dependent control characters within the message. The data format must be 3270 data stream or SNA character stream (SCS). Both are not supported by Telnet.

LUNAME|SCAN

Specifies that the character strings listed in Table 1 are replaced with the appropriate values in the position in the message where the character string occurred. The entire string specified by BUFFER is searched, using the character @. System symbolics are also replaced with their appropriate value. When using the system symbolics in the USS table, an extra ampersand (&) must be prepended to the system symbolic for the assembler compiler to create the correct output. For example, system symbolic &sysname. must be in the table as '&&sysname. for the compiled output to be '&sysname.'

Table 1. Variables substituted for USSMSG
Character string	Message text	Format
@@@@DATE	Current Date	8 bytes, in the format specified by the DATEFRM and DATEDLM operands on the USSTAB macroinstruction.
@@@@@@@@@IPADDR @..@IPADDR(1)	Client IP Address	15 bytes, leading 0's suppressed, left-aligned, with trailing blanks if needed.
@...@IPHOSTNAME (2)	Client host name	40 bytes, name left-aligned with trailing blanks if needed.
@@LUNAME (3)	Client LU Name (SLU)	8 bytes, name left-aligned with trailing blanks if needed.
@@PRT	Client Port Address	5 bytes and leading 0's are not suppressed.
@@@@RUNAME	Failing operation Name	10 bytes, name left-aligned with trailing blanks if needed.
@@@SENSE	Sense Code or Return Code	8 bytes.
@@@@TIME	Current Time	8 bytes in the HH_MM_SS format, where an underscore (_) is the delimiter specified on the TIMEDLM operand of the USSTAB macroinstruction.
@HOSTNET @@@NETID @...@NQN (4) @@SSCPNM @@@@@@@@@@ZONEID		Placeholders for Telnet. Accepted for use, but are set to blanks.
Notes: IPv6 IPADDR must be preceded by 33 @ symbols. IPHOSTNAME must be preceded by 30 @ symbols. @@LUNAME is substituted when it is known. For TN3270 connections, the LU name is not known until after the MSG10 screen is sent to the end-user because the application name is not yet known. NQN must be preceded by 14 @ symbols.

message_id

Specifies which message or messages are defined by this macroinstruction. Table 2 shows the default table variable substitution and examples.

For terminal operator messages, enter decimal integers in the range 0 - 14. The numbers 0 - 14 correspond to the USS messages with message IDs of USSMSG00 through USSMSG14, respectively.

Restriction: USSMSG00 is not defined in the IBM-supplied USS table. If you do not define this message, no message is sent in this case.

Table 2. Default table variable substitution
Message	Variable	Example
MSG00	Command	% COMMAND ACCEPTED
MSG01	Command	INVALID % COMMAND SYNTAX
MSG02	Command	% COMMAND UNRECOGNIZED
MSG03	Command parameter	% PARAMETER EXTRANEOUS
MSG04	Command parameter Command parameter value	% PARAMETER VALUE %(2) NOT VALID
MSG05	None	UNSUPPORTED FUNCTION
MSG06	Message not used	Not applicable — NOT USED BY TELNET
MSG07	LU name Operation that failed Sense Code 3 or Return Code. See message EZZ6035I for return code explanation.	%(1) UNABLE TO ESTABLISH SESSION — %(2) FAILED WITH SENSE %(3)
MSG08	None	INSUFFICIENT STORAGE
MSG09	Message not used	Not applicable — NOT USED BY TELNET
MSG10	None	A 3270 data format screen
MSG11	Message not used	Not applicable — NOT USED BY TELNET
MSG12	None	REQUIRED PARAMETER OMITTED
MSG13	Text after IBMTEST echoed back	IBMECHO %
MSG14	Message number that could not be displayed	USS MESSAGE % NOT DEFINED

OPT=BLKSUP|NOBLKSUP

BLKSUP specifies that extraneous blanks are suppressed from the message. Any sequence of two or more blanks is converted into a single blank. NOBLKSUP specifies that extraneous blanks are not suppressed from the message. Any sequence of two or more blanks is presented unchanged in the message.

message_text

Specifies the text to use in the USS messages identified by the MSG operand. Within message_text, place any combination of the character strings described in Table 1. Telnet places the strings with the values shown in the table.

Rule: Blank suppression always occurs, even if OPT=NOBLKSUP is coded.

Usage notes

For TN3270E, this limitation exists. Unless specific IP-to-LU mapping is used, the LU name is not known for non-TN3270E sessions until an application is chosen from the MSG10 screen. Therefore, no @@LUNAME substitution takes place on the MSG10 screen for non-TN3270E sessions.