Message formats

Message formats and logging versions

A message sent by an authorized user program must not exceed 31 Kbytes. Longer messages are rejected with REJ1. Messages to be received by the user program thus also have a maximum size of 31 Kb plus the length of the possibly added header (see the NBMHE macro on "NBMHE macro"), since messages originating from other senders are in any case much smaller (for instance, the maximum length of a message output with MSG7X is 4 Kb).

The text of these messages always has the same format as for input and output at physical consoles (see previous chapter). Additional formats arise only if the authorized user program is acting as a server of a special operator command. These enhancements are described from "Special operator commands in authorized user programs" onwards.
However, pure text format is unsuitable for automatic evaluation of the messages received, since each individual piece of information, e.g. the value of a particular insert in a message, would first have be searched for in the text. The format of output texts is not, however, a guaranteed interface that will not alter when a version is changed.
The system thus makes it possible to exchange formatted messages with authorized user programs, which contain additional information other than text. This is controlled by the logging version that requests the authorized user program which establishes the connection to $CONSOLE. This procedure is different for connections under generated and dynamic authorization names, and is described in the corresponding sections on "Connections with generated authorization names". However, the meaning of the selected logging version is always the same.

Logging version 0

This represents the same declaration that the exchange of messages between the system and the authorized user program is restricted to message text in both directions. Additional information is not exchanged.

Logging version 1

If the authorized user program with the $CONSOLE interface declares logging version 1, the system still expects only text in known formats to be entered. When sending messages by the authorized user program there is thus no difference from logging version 0.However, the authorized user program receives messages from the system in expanded form, comprising a header, the text itself, as it would have been transmitted with logging version 0, and, if the message was one output with MSG7[X], a filler byte followed by a data-oriented description (“mapping format”) of the structure of the message.
A DSECT for describing the message header can be generated with the NBMHE macro, described below.
For the structure and contents of the data-oriented message description, see the description of the NBMAP macro on "NBMAP macro".

Logging version 2

If the authorized user program declares logging version 2 with the $CONSOLE interface, it receives all messages from the system in expanded form. As regards the receipt of messages by the authorized user program, there is thus no difference to logging version 1.Messages sent from the authorized user program to the system must, however, have the same expanded form; it is not sufficient merely to transmit the straightforward text.Generally, creating the message header for the authorized user program merely makes extra work (and sources of error), but entails no particular benefit. The only time it is necessary to user logging version 2 is if the authorized user program is to be used as a server for a manageable special operator command. The special features associated with this are described on "Special operator commands in authorized user programs". 

NBMHE macro

The NBMHE macro defines the format of the message header. The Assembler interface has the following call format:

Macro	Operands
NBMHE	MF=D/C, PREFIX=prefix, MACID=macid, VER=1/2/3

Users are not permitted to specify VER=1!

The header has the following structure:

Parameter	V	DS	AT	LH	L2	L1	D	AK	SP	BC	RC2	RC1	FL	UID
Apples for version	123	123	123	123	123	123	123	23	23	23	23	23	3	3

where:

V	Version number of the NBMHE macro which generates this structure; 1 byte
DS	Dialog status byte; 1 byte X'80' Logon dialog is running X'40' Connection provisionally accepted X'10' Final acceptance of the logon X'08' Logon rejected X'04' Operator logon requested X'02' Password requested
AT	Job type; 1 byte Values for macro V01: %?/.*; Additional values as of macro V02: +!&:
LH	Length of the header; 2 bytes
L2	Displacement to the data-oriented section; 2 bytes (L2=0000,if there is no data-oriented section (described with NBMAP))
L1	Length of the text-oriented section; 2 bytes
D	Message destination; 4 bytes

Notes on individual fields

Most NBMHE fields are relevant only in particular contexts, as shown in the table. If the particular circumstance is not given, this means that when messages are received by the system, the field is uniformly undefined, and when messages are sent by the system, the contents of the field are not evaluated by the system, and so can be chosen at random.

For reasons of clarity, the logon dialog of the authorized user program dependent on the type of authorization name used is described separately, see "Connections with generated authorization names". The table relates to the exchange of messages - separate from the type of authorization name - after a connection has been successfully established (dialog status byte = 0).

V	Always relevant The version number is determined by the VER parameter of the NBMHE macro. The system always uses the latest version for its messages. The user program is not, however, obliged to use the same version when sending messages; with the exception of version 1, the system accepts all lower versions as compatible and also accepts possible higher versions with the restriction that newly added fields cannot of course be taken into account.
DS	Always relevant The dialog status byte shows which phase of the logon dialog the authorized user program has reached. Values other than zero can occur only during the logon dialog. After the connection has been successfully established, the byte is always 0.
AT	Always relevant Indicates the type of message (see "Communication between operators").
LH	Length of the header and simultaneous - since the text of the message follows directly on from the header - the displacement from the start of the message to the text. The field must correspond to the specified NBMHE version (i.e. 25 bytes for version 2, 34 bytes for version 3). To make sure it is also possible to work with future versions, the length must nevertheless be taken from the length field.
L2	(DLL2) Always relevant Displacement from the start of the message to the data-oriented section (NBMAP). If no data-oriented section is present, the displacement is 0. Important: if a data-oriented section is present, it must not immediately follow the text of the message, but must be separated from it by at least one filler byte. L2 is thus inevitably larger than LH+L1.
L1 D AK	(DLL1) Always relevant Only relevant for messages received Only relevant when receiving commands (AT = “ / ”) and additional command information (AT = “ : ”) and when sending messages as part of command handling (for details, see the relevant section on "Special operator commands in authorized user programs").
SP	Only relevant when sending messages This byte must always be set to zero. Other values are reserved for system applications.
BC	Only relevant if SP is not equal to zero (i.e. exclusively for system applications).
RC2	Only relevant for “command termination” messages (AT = “ ! ”).
RC1	Only relevant for “command termination” messages (AT = “ ! ”).
FL	Only relevant when receiving commands (AT = “ / ”). The term “SCI task” here relates to a user task with the privilege needed to enter the command (in the case of self-defined special operator commands this need not be the OPERATING privilege).
UID	Only relevant when receiving commands (AT = “ / ”).

The version number of the header should not be confused with the logging version number of the connection.

The field LH is at displacement X'03' in the header in all versions. It shows the displacement to the start of the following text, as this starts immediately after NBMHE.

NBMAP macro

The NBMAP macro defines the message trailer. The Assembler interface has the following call format:

Macro	Operands
NBMAP	MF=D/C/L,PREFIX=chars 1, MACID=macid 1..3, VERSION=1 ,MSGKEY=chars 7..7,MSGRC=chars 1..1 ,MSGWEIGHT=msgweight,MSGINSNUM=integer 0..15 ,INSERTS=((length1,distance1),...,(length,distancex))

The structure is as follows:

IL

ID

IL

ID

...

IL

ID

V

MK

RC

WC

NI

INS0

INS1

INSn

V	Version number of the NBMAP macro which generates this structure; 1 byte
MC	Message code; 7 bytes
RC	Routing code; 4 bytes (left-justified, remaining positions filled with 0)
WC	Weight of the message; 1 byte
NI	Number of inserts; 1 byte
IL	Length of current insert; 2 bytes
ID	Displacement of current insert from start of message text; 2 bytes
INS0 .... INSn		0...n message inserts

Example using the message header V02