General
Application area: | Messages; see "Messages" |
Macro type: | Type S, MF format 3: C/D/L/M/E form; see "S-type macros" |
Register contents may be specified only in the M form of the macro.
Macro description
The MSG7X macro outputs a system message to SYSOUT, SYSLST, the operator console, a user program area or an S variable. The specified message code must contain 7 characters.
The MSG7X macro uses the new operand list layout (with standard headers; see "Standard header").
Every system message has a 7-character message code. The first 3 characters of the code denote the message class; the remaining 4 characters are used for consecutive numbering within a class. System messages can contain variable sections “(&nnn)” that can be replaced by inserts.
Macro format and description of operands
MSG7X |
ID=msgid / (r1) / (class,(r)) / (,(r)) / (class,(addr)) / (,addr) ID=msgid / (r1) / (class,(r)) / (,(r)) / (class,(addr)) / (,addr) [,INSERT={(insertlength,{addr / (r) / ’insert’}) / ((insertlength,{addr / (r) / ’insert’}),...) / ((r1),(r2)) / (((r1),(r2)),...) / number / NONE } [,LAN='language'] ,DEST=SYSOUT / SYSLST / CONSOLE / (destination,...) / NONE [,UCDEST='destcode' / destaddr / (r) / N] [,REPLY={(replylenght,{addr / (r)}) / ((r1),(r2)) / N}] [,BUFFER= {(bufferlength,{addr / (r)}) / ((r1),(r2)) / N}] ,MAP=NO / YES ,DMS=APPL / NOTAPPL / NA ,BUFFUSE=INTERNAL / EXTERNAL ,DEFTEXT=NONE / (textlength,addr) / (textlength,(r)) / ((r1),(r2)) ,TIMER=UNLIMITED / (r) / wert ,TIMESTAMP=NO / YES ,DATESTAMP=NO / YES ,MF=D / C / L / E / M [,PARAM=addr / (r)] ,PREFIX=X / p ,MACID=MSG / macid |
ID=
Specifies the message code of the system message to be output.
msgid
Specifies a 7-character message code.
(class,addr)
Modifies the message code in the parameter list.
(class,(r))
This operand value may be specified only in conjunction with MF=M.
| message class |
| symbolic address (name) of a field containing the new message number |
| register containing the new message number |
(,addr)
Modifies the message number in the parameter list.
(,(r))
This operand value may be specified only in conjunction with MF=M.
| symbolic address (name) of a field containing the new message number |
| register containing the new message number |
INSERT=
Specifies up to 30 lengths and addresses of inserts. An address reference is created in the message processing operand list for each entry.
If more inserts are specified than can be accommodated by the message, excess inserts are ignored. An insert consisting solely of blanks is shortened to a single blank.
Trailing blanks in an insert are suppressed. The character X'01' must be entered at the end of an insert to prevent the suppression of blanks. When the character X'01' is encountered during message processing, all blanks that precede it are retained.
If insertlength=0 and addr=0 are specified, the system assumes the default value from the message file for the insert. If no default value is specified in the message file the insert is omitted.
If a message text contains more inserts than are specified in the macro call, the default value is assumed for every excess insert. The substitute insert (&nn) is used if no default value is present.
If MF=M is specified, an address reference is created for all inserts specified for INSERT. For example, calling MF=M,INSERT=(((R1),(R2)),((R3),(R4))) changes inserts 0 and 1 in the data area but not 2 or 3.
All inserts defined previously in the operand list are ignored. The number of inserts defined for MF=M must be less than or equal to any maximum number predefined by MF=C or MF=D.
(insertlength,...)
| length of the insert |
| symbolic address (name) of the area with the insert |
| register containing the insert address |
| direct specification of the insert (length of string: max. 4 |
If insertlength=0, the insert must begin with a record length field (4 bytes) and is thus always at least 4 bytes long.
| length of the insert |
| reserved. |
Inserts may be skipped by entering commas for omitted positions, e.g.
INSERT=(,(insertlength2,addr2),,(insertlength4,addr4)). Inserts omitted in this way are replaced by their default values or by a blank character string (&nn).
The sum of the insertion lengths must be <= 4079 bytes. An insertion list must be enclosed within additional paretheses.
If output is to console, the sum of all insertions must be <= 218 bytes.
((r1),(r2))
| register containing insert length |
| register containing insert address. |
This may only be specified with MF=M.
An insertion list must be enclosed within additional paretheses.
number
Number of INSERTs for which space is to be reserved in the data area for message processing.
With MF=C/D, the number is 15 by default.
With MF=M, the number of inserts in the data area may be changed.
NONE
All inserts defined previously are ignored.
This operand value may be specified only in conjunction with MF=M.
LAN='language'
Specifies the language to be used for message output. This operand is ignored if DEST=CONSOLE is specified.
'language'
1 letter to identify the language: D = German, E = English.
For additional options please consult system administration. The default value is defined by the system parameter MSGLPRI; this value is also assumed in the event of invalid specifications.
REPLY=
Defines a reply area. The area must be aligned on a halfword boundary and begin with a record length field (4 bytes: bytes 1-2: length of the reply; bytes 3-4 reserved). Before the macro is executed, bytes 1-2 must contain the length of the reply area (<= 4095 bytes). When the macro is executed, the current length of the reply is entered in bytes 1-2.
Lowercase letters are converted to uppercase when entered via the REPLY operand.REPLY may be specified only in conjunction with DEST=SYSOUT/CONSOLE.
If “?” is entered as a reply and is reserved as a codeword in MIP, MIP displays the meaning of the message in question and the action required, before the message is output again in response.
(replylength,...)
| length of the reply area > 4 bytes |
| symbolic address (name) of the area |
| register containing the address of the area |
((r1),(r2))
| register containing the length of the reply area |
| register containing the address of the area |
May only be specified if MF=M.
N
No reply area is generated in the CSECT/DSECT.
This specification is required for the structuring of the CSECT/DSECT; it may be specified only in conjunction with MF=C/D.
DEST=
Designates destinations for the converted system message. Only DEST=SYSOUT / CONSOLE may be specified in conjunction with REPLY.
SYSOUT
Output to SYSOUT. This is the default setting if another output location is not specified with BUFFER. If an output location is specified with BUFFER and output to SYSOUT is desired, DEST=SYSOUT must be specified explicitly.
If an S variable was declared and the variable stream was directed into it, and the message is a guaranteed one, output is also to the S variable.
SYSLST
Output to SYSLST.
CONSOLE
Output to the operator console.
(destination,...)
Combination of the above-mentioned destinations; entry in parentheses, separated by commas.
NONE
Deletes the destinations SYSOUT, SYSLST and CONSOLE from the operand list. This operand value may be specified only in conjunction with MF=M. Note that the operand list must always contain at least one destination, e.g. a special area designated for this purpose (see the BUFFER operand).
BUFFER=
Specifies an area to which the converted system message is to be transferred. If output to SYSOUT is also desired, DEST=SYSOUT must be explicitly specified.
BUFFER must be aligned on a halfword boundary. A record length field is entered in the first 2 bytes (WROUT format):
| length of the area |
| reserved |
| output control character |
| message text |
(bufferlength,...)
bufferlength | = length of the area > 16 bytes |
| symbolic address (name) of the area |
| register containing the address of the area (may be specified only if |
The buffer length must be <= 4095 bytes.
((r1),(r2))
| register containing the length of the message area. |
| register containing the address of the area. |
May only be specified if MF=M.
N
No area for the converted system message is generated in the CSECT/DSECT.
This specification is required for the structuring of the CSECT/DSECT; it may be specified only in conjunction with MF=C/D.
MAP=
Specifies whether BUFFER is given another structure (mapping format).
NO
BUFFER is created in the WROUT format.
YES
BUFFER is created in the mapping format (see below).
UCDEST=
UCON destination (UCON=Universal Console); (see the “Introduction to System Administration” [10 (Related publications)]).
The destination of a message can be specified as follows:
mnemonic device name for a particular console
routing code for consoles and authorized user tasks which are allocated a particular area of activity
authorization name for an authorized user task.
'destcode'
The following entries are permissible for 'destcode':
'(mn)'
mn: 2-character mnemonic device name.'< x'
x: routing code; The<character must be specified.'name'
name: name of the user task (4 characters).
destaddr
Symbolic address (name) of an area (4 bytes) with the entry for “destcode”. Left-justified entries; alignment on a word boundary.
(r)
Register containing the address of the area (4 bytes). May be specified only if MF=M.
N
No field for “destcode” is to be generated in the CSECT/DSECT.
This specification is required for the structuring of the CSECT/DSECT; it may be specified only in conjunction with MF=C/D.
DMS=
Specifies the message search mechanism.
APPL
The message is sought with the aid of DMS (message files and DLAM area).
NOTAPPL / NA
The message is sought only at system level in the DLAM area (without DMS). Reply if the requested message is not found:
msgid,(DMS NOT IN MEMORY),<program pointer>,<modul>,<inserts>
BUFFUSE=
Specifies whether the message is to be stored in an S variable via a variable stream (SYSMSG) and can be output by means of the HELP-MSG-INFORMATION MSG-ID= *LAST command (in other words, without explicitly specifying the message number).Specifying BUFFUSE is relevant only of the output does not go to SYSOUT
(DEST != SYSOUT) and a transfer area was specified with the BUFFER operand.
If the message is (also) output to SYSOUT, and if it is a guaranteed message, it is always output to the S variable (where one was declared and the variable stream was directed into it). The variable stream includes only “guaranteed messages”. See the manuals
“SDF-P” [21 (Related publications)] and “Utility Routines (MSGMAKER)” [27 (Related publications)].
INTERNAL
Output is not directed to a variable stream. The message cannot be output by means of the HELP-MSG-INFORMATION MSG-ID=*LAST command (in other words, without explicitly specifying the message number.
EXTERNAL
If an S variable was declared and the variable stream directed to it (with the command ASSIGN-STREAM or EXECUTE-COMMAND or with the CMD or OPSGEN macro), the message is output to this S variable.
The message code, the text of the message and the default values of the inserts are output. The message must be a guaranteed one, since otherwise it is not included in the variable stream. If the message is the last one output by the task, it can be output with the command HELP-MSG-INFORMATION MSG-ID=*LAST.
DEFTEXT=
Refers to a default message text. This default message text is output if the required message is not defined or if the required message or MIP task is not currently available. A corresponding return code is output. The default message text must be <= 4079 bytes.
NONE
No default message text specified.
(textlength,...)
| = length of area |
| symbolic address (name) of area |
| register containing address of area (may be specified only if MF=M) |
((r1),(r2))
| register containing length of default message text. |
| register containing address of area. |
May be specified only if MF=M.
TIMER=
Specifies the maximum waiting time for a reply (REPLY operand) after a message is sent to SYSOUT.
If no reply is received within the time specified, the corresponding return code is output.
UNLIMITED
Unlimited waiting time.
(r)
r: register containing the waiting time. May be specified only if MF=M.
value
Waiting time, which can be between 10 and 3600 seconds.
TIMESTAMP=
Allows additional output of local system time.
NO
Local system time is not output.
YES
Local system time is output in ISO4 format in addition to the message. The output then has the following format:'% hh:mm:ss msgid text'
where:
| hour |
| minute |
| second |
| message ID |
| message text |
Note
For representation of time stamps, see also CTIME macro ("CTIME - Time stamp calculations").
If MIP cannot read a time due to an internal error, the following is output: '% HH:MM:SS msgid text'
DATESTAMP=
Allows additional output of date.
NO
Date is not output.
YES
The date is output in ISO4 format in addition to the message. The output then has the following format:'% yyyy-mm-dd msgid text'
where:
| year |
| month |
| day of the month |
| message ID |
| message text |
Note
For representation of time stamps, see also CTIME macro ("CTIME - Time stamp calculations").
If MIP cannot read a date due to an internal error, the following is output:'% YYYY-MM-DD msgid text'
If both date and time output is required, the date comes before the local system time.
MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. PREFIX, MACID and PARAM), see section “S-type macros”. The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
A PREFIX can be specified in the C form, D form or M form of the macro and additionally a MACID in the C form or M form (see section “S-type macros”).
Notes
The total length of a message including the message code must be <= 4079 bytes. Any characters in excess of this are automatically cut.
If output is to the console, the maximum length of a message, including message key is only 230 bytes.
Trailing blanks are automatically suppressed.
Message output to SYSOUT, SYSLST or to a BUFFER area always begins with the character
%(e.g.'%NMH1121 <text>').
If, however, the message is output to the console, it begins with a blank before the%(e.g.' %NMH1121 <text>').
Mapping format
The mapping format specifies the structure of the BUFFER area in the case of MAP=YES. Various entries (mapping list) are prefixed to the structure defined under BUFFER.
Structure of the mapping format:
| length of the mapping list |
| C'MP' |
| entries |
| remainder of structure as under BUFFER (WROUT format). |
The entries contain information on
the inserts
the message code
the routing code
the message weight
as necessary, slack bytes for alignment of the WROUT buffer.
The entries are stored in the formats below:
Notes on the macro call
If output is in mapping format, an entry with length =0 and address=0 stands for an insert which does not exist. Such entries are output only if the inserts of a message are not consecutively numbered.
Inserts for which no current value is available, however, are described by an entry with length=0 and the distance to the defined insert position. The default text of the insert or, if no default text is defined, the standard insert (&xx) is found starting at this distance.
If another MSG7X parameter list for an input is to be constructed from the mapping output, the distance for non-specified inserts must be reset to 0 because all other distance values in conjunction with length=0 are regarded as defining an insert which begins with a 4-byte record length field.
Return information and error flags
Standard header:
+---------------+ | | | | | |c|c|b|b|a|a|a|a| +---------------+
A return code relating to the execution of the MSG7X macro is transferred in the standard header
(cc=Subcode2, bb=Subcode1, aaaa=Maincode; Subcode2 is only used with an I/O error and then contains the main return code of the WROUT or WRTRD macro):
X'cc' | X'bb' | X'aaaa' | Meaning |
X'00' | X'0000' | MSG7X macro executed successfully | |
X'cc' | X'04' | X'0001' | Abnormal termination of output (SYSOUT, SYSLST or CONSOLE). |
X'08' | X'0001' | Operand error: invalid specification for message number, area address, | |
X'0C' | X'0001' | Invalid request for a reply, e.g. in batch mode or when nonspecifiable | |
X'10' | X'0001' | No memory space available | |
X'14' | X'0001' | BREAK during execution of the WROUT macro | |
X'18' | X'0001' | Message text was truncated on transfer to the output area | |
X'20' | X'0001' | Message output was aborted | |
X'00' | X'41' | X'FFFF' | MIP subsystem not loaded |
X'02' | X'00' | Message not defined | |
X'03' | X'00' | MIP task not available | |
X'05' | X'00' | DMS subsystem not loaded | |
X'06' | X'00' | Message not available. Error in file |
Other return codes which, in accordance with conventions, apply to all macros are given in the table “Standard return codes” (Standard header).
The calling program is terminated when the following errors occur:
The data area is not assigned to the caller.
The data area is not aligned on a word boundary.
The data area is protected against write access.
Example 1
This example shows various options for seeking and outputting messages.
MSG7X1 START
MSG7X1 AMODE ANY
MSG7X1 RMODE ANY
PRINT NOGEN
BALR 3,0
USING *,3
*
SYSFL 'SYSLST=LST.MSG7X'
MFE1 MSG7X MF=E,PARAM=MFL1 —————————————————————————————————————— (1)
MFE2 MSG7X MF=E,PARAM=MFL2 —————————————————————————————————————— (2)
WROUT TEXT,ERROR,PARMOD=31
MFE3 MSG7X MF=E,PARAM=MFL3 —————————————————————————————————————— (3)
WROUT TEXT,ERROR,PARMOD=31 ————————————————————————————————— (4)
SYSFL 'SYSLST=(PRIMARY)'
*
ERROR TERM
*
MFL1 MSG7X MF=L,ID=DMS0E27,DMS=NOTAPPL,LAN='D'
MFL2 MSG7X MF=L,ID=DMS0E27,DEST=(SYSLST,SYSOUT),LAN='D'
MFL3 MSG7X MF=L,ID=SCP0976,DEST=SYSLST,BUFFER=(75,TEXT)
*
TEXT DC Y(TEXTEND-TEXT)
DS 3X
DS 0CL75
DC C'message output via WROUT: '
TEXTEND EQU *
END
Runtime log:
/start-assembh % BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED % ASS6010 <ver> OF BS2000 ASSEMBH READY //compile source=*library-element(macexmp.lib,msg7x1), - // compiler-action=module-generation(module-format=llm), - // module-library=macexmp.lib, - // listing=parameters(output=*library-element(macexmp.lib,msg7x1)) % ASS6011 ASSEMBLY TIME: 508 MSEC % ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES % ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS % ASS6006 LISTING GENERATOR TIME: 82 MSEC //end % ASS6012 END OF ASSEMBH
/start-executable-program library=macexmp.lib,element-or-symbol=msg7x1 % BLS0523 ELEMENT 'MSG7X1', VERSION '@' FROM LIBRARY ':2OSG:$QM212.MACEXMP.LIB' IN PROCESS % BLS0524 LLM 'MSG7X1', VERSION ' ' OF '<date> <time>' LOADED % DMS0E27 ( DVS NICHT VERFUEGBAR ) --PC=00000034 IN P1-MODULE=********--———————————————————————————————————————————————— (5) % DMS0E27 FEHLER BEIM SCHLIESSEN EINER DATEI. EIN- AUSGABE MIT HARDWARE-FEHLER BEENDET ———————————————————————————————————————————— (6) message output via WROUT: % SCP0976 LOGICAL VALIDATION PROBLEM DURING COMMAND PROCESSING ——————— (7) Output on SYSLST: % DMS0E27 FEHLER BEIM SCHLIESSEN EINER DATEI. EIN- AUSGABE MIT HARDWARE-FEHLER BEENDET % SCP0976 LOGICAL VALIDATION PROBLEM DURING COMMAND PROCESSING
(1) | The message |
(2) | The message |
(3) | The message |
(4) | The macro WROUT writes the contents of the macro |
(5) | Output of the message from (1). The message is output in German because of the LAN=’D’ operand. |
(6) | Output of the message from (2). The message is output in German because of the LAN=’D’ operand. |
(7) | Output of WROUT. |
Example 2
The following example shows message output being directed to an S variable. The
S variable must be declared before calling the program and the variable stream SYSMSG must be assigned to it. Only the guaranteed messages are included in the SYSMSG variable stream.
MSG7X2 START
MSG7X2 AMODE ANY
MSG7X2 RMODE ANY
PRINT NOGEN
BALR 3,0
USING *,3
*
MFE1 MSG7X MF=E,PARAM=MFL1
MFE2 MSG7X MF=E,PARAM=MFL2
MFE3 MSG7X MF=E,PARAM=MFL3
MFE4 MSG7X MF=E,PARAM=MFL4
*
ERROR TERM
*
**** Definitions ****
*
MFL1 MSG7X MF=L,ID=CMD0500,BUFFER=(250,BUF),MAP=YES, *
DEST=(SYSOUT,SYSLST) ————————————————————————————————— (1)
MFL2 MSG7X MF=L,ID=DMS0DF8,BUFFER=(250,BUF),MAP=YES,DEST=SYSOUT — (2)
MFL3 MSG7X MF=L,ID=SCP0976,BUFFER=(250,BUF),DEST=SYSLST ————————— (3)
MFL4 MSG7X MF=L,ID=DMS0574,BUFFER=(250,BUF),DEST=SYSLST, *
BUFFUSE=EXTERNAL ————————————————————————————————————— (4)
*
BUF DS 0CL250
DC Y(ENDBUF-BUF)
DS 3X
DS CL245
ENDBUF EQU *
END
Runtime log:
/start-assembh % BLS0500 PROGRAM 'ASSEMBH', VERSION '<ver>' OF '<date>' LOADED % ASS6010 <ver> OF BS2000 ASSEMBH READY //compile source=*library-element(macexmp.lib,msg7x2), - // compiler-action=module-generation(module-format=llm), - // module-library=macexmp.lib, - // listing=parameters(output=*library-element(macexmp.lib,msg7x2)), - // test-support=*aid % ASS6011 ASSEMBLY TIME: 405 MSEC % ASS6018 0 FLAGS, 0 PRIVILEGED FLAGS, 0 MNOTES % ASS6019 HIGHEST ERROR-WEIGHT: NO ERRORS % ASS6006 LISTING GENERATOR TIME: 80 MSEC //end % ASS6012 END OF ASSEMBH /declare-var msg(type=structure),mult-elem=*list —————————————————————— (5) /assign-stream sysmsg,to=*var(msg) /start-executable-program library=macexmp.lib,element-or-symbol=msg7x2 % BLS0523 ELEMENT 'MSG7X2', VERSION '@' FROM LIBRARY ':2OSG:$QM212.MACEXMP.LIB' IN PROCESS % BLS0524 LLM 'MSG7X2', VERSION ' ' OF '<date> <time>' LOADED % CMD0500 INVALID DESCRIPTION OF COMMAND OR STATEMENT IN CURRENT SYNTAX FILE % DMS0DF8 EXPECTED VSN '(&01)' FOR FILE '(&02)', VSEQ '(&03)' NOT MOUNTED ON DEVICE '(&00)'. VSN '(&04)' FOUND INSTEAD. REPLY (0=EXIT; 1=RETRY; 2=DISPLAY LABEL; =ACCEPT) /assign-stream sysmsg,to=*dummy ——————————————————————————————————————— (6) /show-var msg MSG(*LIST).MSG-TEXT = % BLS0523 ELEMENT 'MSG7X2', VERSION '@' FROM LIBRARY ':2OSG:$QM212.MACEXMP.LIB' IN PROCESS MSG(*LIST).MSG-ID = BLS0523 MSG(*LIST).I0 = MSG7X2 MSG(*LIST).I1 = @ MSG(*LIST).I2 = :2OSG:$QM212.MACEXMP.LIB MSG(*LIST).MSG-TEXT = % BLS0524 LLM 'MSG7X2', VERSION ' ' OF '<date> <time>' LOADED MSG(*LIST).MSG-ID = BLS0524 MSG(*LIST).I0 = MSG7X2 MSG(*LIST).I1 = MSG(*LIST).I2 = <date> <time> MSG(*LIST).MSG-TEXT = % BLS0551 COPYRIGHT (C) . . . MSG(*LIST).MSG-ID = BLS0551 MSG(*LIST).I0 = FUJITSU TECHNOLOGY SOLUTIONS MSG(*LIST).I1 = 2012 MSG(*LIST).MSG-TEXT = % CMD0500 INVALID DESCRIPTION OF COMMAND OR STATEMENT IN CURRENT SYNTAX FILE MSG(*LIST).MSG-ID = CMD0500 MSG(*LIST).MSG-TEXT = % DMS0574 DMS ERROR CODE '(&00)' OCCURRED WHEN
DELETING SYSTEM FILE. COMMAND NOT PROCESSED MSG(*LIST).MSG-ID = DMS0574 MSG(*LIST).I0 = (&00)
(1) | The message with message code |
(2) | The message with message code |
(3) | The message with message code |
(4) | The message with message code |
(5) | A composed “List”-type S variable called ABC is declared. Each guaranteed message is stored in the structured S variable ABC as a list element. Elements are added to the S variable until the assignment to SYSMSG is terminated. |
(6) | The assignment of the variable stream SYSMSG to the S variables ABC is canceled. The contents of the S variables ABC are displayed. In addition to the messages written by the program in the S variable ABC, the S variable also contains guaranteed messages which were output when loading the MSG7X2 module. These were also output to the S variable ABC when loading the MSG7X2 module after the redirection of the variable stream SYSMSG. |