gtpg2m5q | General Macros |
This general macro edits and sends a message to the system operator or any other designated terminal. It constructs the message block and provides facilities for converting binary values into EBCDIC, decimal, or hexadecimal and for editing the message.
Each time WTOPC is called a single line or a block of text is associated with it. In the discussion that follows we assume each WTOPC is for a single line and use the term message lines to refer to lines or blocks.
The WTOPC macro functionally enhances the ROUTC, SENDC, or CSMP interface for system messages. The format of the message produced by the WTOPC macro is in the standard TPF system format:
xxxxnnnnl hh.mm.ss message text
Where:
Format
|
|
Notes:
|
|
When the text is copied into the buffer, the length of the message text is inserted into the first byte of the buffer, and the remainder of the text is inserted in subsequent bytes.
Use the CHAIN operand to link WTOPC calls together to produce an uninterrupted display of message lines in their original order. The format of the CHAIN operand is:
For example, if you code 3 WTOPC macros with CHAIN=YES on all three, ENDOFM=NO on the first two, and ENDOFM=YES on the last one, the display could be as follows:
CSMP0097I 00.00.00 CPU-B SS-BSS SSU-HPN IS-01 xxxxnnnnl 00.00.00 This is the first line of the message 00.00.00 This is the second line of the message 00.00.00 This is the third (last) line of the message
Although this does not seem any different from the display using just the ENDOFM operand, there are several differences. CHAIN=YES prevents other output messages from interrupting a multiple line display and ensures the output lines appear in the same order that the WTOPC macros were issued. When used with the HEADER and ENDOFM operands, CHAIN=YES can be used to format long displays.
CHAIN=YES is NOT allowed when ECB=NO. In other words, CP code executing without an ECB cannot use the CHAIN parameter, but this does not mean that CP code cannot issue a multiple-line message. (Refer to the HEADER parameter to see how this is accomplished.) If CHAIN is coded with ECB=NO, it will be flagged and ignored.
For example, if you code:
WTOPC TEXT='TOTAL 5',COMP=YES
the line is displayed as:
TOTAL 5
When DISP is not coded, the message text is built and sent to the designated terminal.
When the DISP parameter is coded, the only correct value for it is 'NONE'. 'DISP=NONE' specifies that no output occurs. The message is built, returned to the BUFFA area, and not sent. When 'DISP=NONE' is used, the BUFFA parameter must also be specified.
For example, if you code:
WTOPC TEXT='COMPLETED',DOT=YES
the line displayed is:
COMPLETED.
CP code normally runs without an ECB. All WTOPC calls from the CP (as well as ECB=NO) must specify UNSOL=YES and XNUM=YES.
ECB creation time is used to identify each chained message, so a WTOPC called by CP code is not able to send chained messages. As a result, the existence or nonexistence of an ECB must be specified by the programmer.
Notes:
Use the ENDOFM operand when you want to suppress prefixing of the message lines following the current message line. The format of the ENDOFM operand is:
For example, if you code ENDOFM=NO, the display will be as follows:
CSMP0097I 00.00.00 CPU-B SS-BSS SSU-HPN IS-01 xxxxnnnnl 00.00.00 This is the first message line 00.00.00 This is the second message line 00.00.00 This is the third message line
Otherwise, if you code ENDOFM=YES (default value) or ENDOFMR=(R6) and R6 contains the value zero, the display will be as follows:
CSMP0097I 00.00.00 CPU-B SS-BSS SSU-HPN IS-01 xxxxnnnnl 00.00.00 This is the first message line CSMP0097I 00.00.00 CPU-B SS-BSS SSU-HPN IS-01 xxxxnnnnl 00.00.00 This is the second message line CSMP0097I 00.00.00 CPU-B SS-BSS SSU-HPN IS-01 xxxxnnnnl 00.00.00 This is the third message line
Nonzero, subsequent lines are not prefixed or
Zero, subsequent lines are prefixed.
If used with CHAIN=YES, ENDOFMR also specifies whether the current message line is the end of the chain.
Use the ENDOFMR operand when you want to suppress prefixing of the message lines following the current message line. The format of the ENDOFMR operand is:
For example, if you code ENDOFMR=(R6) and R6 contains a value other than zero, the display will be as follows:
CSMP0097I 00.00.00 CPU-B SS-BSS SSU-HPN IS-01 xxxxnnnnl 00.00.00 This is the first message line 00.00.00 This is the second message line 00.00.00 This is the third message line
If you code ENDOFMR=(R6) and R6 contains the value zero, the display will be as follows:
CSMP0097I 00.00.00 CPU-B SS-BSS SSU-HPN IS-01 xxxxnnnnl 00.00.00 This is the first message line CSMP0097I 00.00.00 CPU-B SS-BSS SSU-HPN IS-01 xxxxnnnnl 00.00.00 This is the second message line CSMP0097I 00.00.00 CPU-B SS-BSS SSU-HPN IS-01 xxxxnnnnl 00.00.00 This is the third message line
Use the HEADER operand if the header is to be suppressed. The format of the HEADER operand is:
For example, if you code:
WTOPC TEXT='FIRST WTOPC MESSAGE',PREFIX =WTOP,NUM=01,LET=I WTOPC TEXT='SECOND WTOPC MESSAGE',HEADER=NO
The following lines are displayed:
WTOP0001I 00:00:00 FIRST WTOPC MESSAGE SECOND WTOPC MESSAGE
Use the LEVEL operand to pass the text in a 381-byte message block in AMSG (AM0SG) format. The output text should be in a 381-byte block and the maximum text count must not exceed 335 (UI0TMX).
The message destination is based on the address in the message and routing codes specified by the ROUT parameter, if any. EBROUT is not used. No text manipulation is performed, therefore the following operands will be considered invalid when the LEVEL operand is coded; COMP, DOT, SUB, DISP, BUFFA, MF, TEXT, TEXTA, and ECB. WTOPC returns to the user with the message block detached.
The format of the MF option is:
When XNUM=NO is coded, the valid range for NUM is decimal 1-255.
When XNUM=YES is coded, the valid range is decimal 1-9999.
When XNUM=NO, the binary number is assumed to be in bits 24-31.
When XNUM=YES, the binary number is assumed to be in bits 16-31.
when XNUM=NO, NUMA must specify a 1-byte field, and
when XNUM=YES, NUMA must specify a 2-byte field.
When this label receives control, the program should not issue any more output.
Notes:
Use the PREFIX operand to precede the message with four characters denoting its origin.
For example, if you code:
WTOPC TEXT='OUTPUT MESSAGE',PREFIX=CVAD,NUM=01,LET=I,... WTOPC TEXT='OUTPUT MESSAGE 2',PREFIX=(R7),NUM=02,LET=I,...
where CVAD is the desired message prefix and R7 contains X'C3E5D1C3' (C'CVJC'), the following lines are displayed:
CVAD0001I 00.00.00 OUTPUT MESSAGE 1 CVJC0002I 00.00.00 OUTPUT MESSAGE 2
Use the PREFIXA operand to precede the message with four characters denoting its origin.
For example, if you code the following:
WTOPC TEXT='OUTPUT MESSAGE 1',PREFIXA=PRFIX,NUM=01,LET=I,... WTOPC TEXT='OUTPUT MESSAGE 2',PREFIXA=EBW068,NUM=02,LET=I,... WTOPC TEXT='OUTPUT MESSAGE 3',PREFIXA=(R6),NUM=03,LET=I,...
where:
PRFIX DC CL4'CVLC',
EBW068 contains X'C3E5D8C3' (C'CVQC'), and
R6 contains the address of a 4-byte, character field containing X'C3E5D4C7' (C'CVMG')
the following lines are displayed:
CVLC0001I 00.00.00 OUTPUT MESSAGE 1 CVQC0002I 00.00.00 OUTPUT MESSAGE 2 CVMG0003I 00.00.00 OUTPUT MESSAGE 3
Use the ROUT operand to specify specific functional support consoles to which the message should be sent. You may specify either the mnemonic, as defined in RTCEQ, or the actual functional support console (1-16).
ROUT=(routing_code1,...,routing_coden...)
Routing codes specified on the WTOPC macro are in addition to any functional support console (FSC) bits set upon entry.
The SUB parameter specifies the type of substitution performed on portions of the message indicated by periods. For each set of periods, specify the type of substitution and the value to be substituted or its address. If the message text does not contain periods, no substitution is performed.
You can specify the SUB parameter in one of the following formats:
Where:
Where:
Where:
The following describes each of the possible substitution pairs. These descriptions are followed by information about length specification and multiple substitution lists.
For example, if register 3 contains the value C0031FC8, the following macro statement:
WTOPC TEXT='VALUE = ...',SUB=(HEX,(R3))
results in the display:
VALUE = FC8
WTOPC TEXT='BUFFER IS LOCATED AT ......',SUB=(HEX,BUFF1)
can result in the display:
BUFFER IS LOCATED AT 0201AC
If you code fewer than eight periods in the message text, leading digits are truncated; leading zeros are not suppressed.
WTOPC TEXT='REG 3 = ......',SUB=(DEC,(R3))
results in the display:
REG 3 = 10345
VALUE EQU 2003
In this example, the following macro statement:
WTOPC TEXT='VALUE IS ......',SUB=(DEC,VALUE+5)
results in the display:
VALUE IS 2008
WTOPC TEXT='HEX VALUE IS .....',SUB=(HEXA,CODE)
WTOPC TEXT='REGISTER 5 - ......',SUB=(HEXA,(R5))
If you code fewer than eight digits, leading digits are truncated; leading zeros are not suppressed.
WTOPC TEXT='COUNT = ......',SUB=(DECA,COUNT)
WTOPC TEXT='SUM = ..........',SUB=(DECA,(3))
BIGNUM DC XL8'00000001FFFFFFFF'
WTOPC TEXT='SUM = ..........................',SUB=(DEC8A,BIGNUM)
results in the display:
SUM = 8 589 934 591
NUMBER DC XL8'0000000000001000'
WTOPC TEXT='SUM = ..........................',SUB=(DEC8A,NUMBER),COMP=YES
results in the display:
SUM = 4 096
When you code periods in the message text for substitution, you must code sufficient periods to allow for the blanks. Thus, to display 8 bytes of information (16 hexadecimal digits), you must code 17 periods in the message text.
For example, to display 7 bytes of hexadecimal data beginning at location STOR in your program, you can code the following:
WTOPC TEXT='STOR: ...............',SUB=(HEX4A,STOR)
This results in the following display:
STOR: 0A23F115 78ACFE
When you code the message text for the substitution, you must code sufficient periods to allow for the blank characters to be inserted.
For example, the following macro statement:
WTOPC TEXT='....................',SUB=(HEX4A,(R6))
results in the display of the first 9 bytes at the address in register 6, in the following format:
hhhhhhhh hhhhhhhh hh
For example, to display 7 bytes of hexadecimal data beginning at location STOR in your program, you can code the following:
WTOPC TEXT='STOR: ..............',SUB=(HEXBA,STOR)
This results in the following display:
STOR: 0A23F11578ACFE
For example, the following macro statement:
WTOPC TEXT='..................',SUB=(HEXBA,(R6))
results in the display of the first 9 bytes at the address in register 6, in the following format:
hhhhhhhhhhhhhhhhhh
WTOPC TEXT='NAME IS ''...........''',SUB=(CHARA,NAME)
causes the 10 characters at location name to be substituted into the message text.
WTOPC TEXT='CODE IS ....',SUB=(CHARA,(R7))
In this example, the first 4 characters at the address indicated in register 7 are substituted in the message line.
Specifying the Length for WTOPC Macro Substitution
In all the examples shown, the length of the argument being substituted was determined by the number of periods in the message text. The number of periods indicated the size of the output field, and indirectly determined the size of the input data area.
For hexadecimal and decimal substitutions, the input data is truncated on the left. To ensure that a decimal number will never be truncated, you can code 10 periods (11 for negative numbers) in the message text where it will be substituted. For hexadecimal data, code 8 periods to ensure that no characters are truncated when a fullword is substituted.
When you are coding substitution lists with the CHARA, CHAR8A, HEX4A, and HEXBA options, however, you can specify the length of the input data field. To do so, code the SUB operand as follows:
SUB=(type,(address,length))
Both address and length may be specified using register notation. For example:
SUB=(HEX4A,(LOC,(R4)))
shows that the characters at location LOC are substituted into the message text; the number of characters is determined by the value contained in register 4, but it cannot be larger than the number of periods coded in the message text.
You can use this method in the special case where only 1 character is to be substituted. Since you must always code at least two periods to indicate that substitution is to be performed, you can code two periods and specify a length of 1, as follows:
WTOPC TEXT='INVALID MODE LETTER ..',SUB=(CHARA,(PLIST+24,1))
Specifying Multiple Substitution Lists
When you want to make several substitutions in the same line, you must enter a substitution list for each set of periods in the message text. For example,
WTOPC TEXT='VALUES ARE ..... AND ......',SUB=(DEC,(R3),HEXA,LOC)
might generate a line as follows:
VALUES ARE -45 AND FFE3C2.
WTOPC TEXT='message text'
If you want a single quotation mark to appear within the actual message text, you must code two of them.
Text specified on the WTOPC macro may be edited so that multiple blanks appear as only a single blank, and a period may be placed at the end of the line, for example:
TEXT='IT ISN''T READY'
will result in:
IT ISN'T READY.
Use the TEXTA operand when you want to send a message contained in a buffer. You may specify either a symbolic address or use register notation. In either case, the first byte at the address specified must contain the length of the message text, for example:
WTOPC TEXTA=MESSAGE
where MESSAGE must be defined as follows:
MESSAGE DC AL1(MSGLEN-MESSAGE-1),AL1(#CAR) DC C'LINE ONE',AL1(#CAR) DC C'LINE TWO' MSGLEN EQU *
will produce:
LINE ONE LINE TWO
Notes:
Unsolicited messages are handled by the unsolicited message package (UMP). Operators may need to issue the LOGU command to display unsolicited messages.
If R15 is available, code WKREG=R15.
If R15 is not available, code WKREG=Rx, where Rx is an available register.
XNUM=NO is the default if the XNUM parameter is not specified.
This parameter is affected by any previous use of WTOPC or DCTMSG. For example: if DCTMSG is coded with XNUM=YES, the following WTOPC must code XNUM=YES or omit the XNUM parameter. In this case, omitting XNUM will result in XNUM=YES being the default.
Entry Requirements
Return Conditions
12 + 6 if HEADER=YES
+ 4 if BUFFA was specified
+ 5 for each substitution that does not specify an explicit length
+ 6 for each substitution that does specify an explicit length
If the default work area is used and the parameter list is too large to fit in it because of too many substitutions, a warning message will be generated.
Examples
WTOPC TEXT='DEFINITION NOT ACCEPTED', X NUM=26,LET=W,PREFIX=VFAC
The following example sends a single line output message from CP code.
WTOPC TEXT='DEFINITION NOT ACCEPTED', X NUM=26,LET=W,PREFIX=VFAC,ECB=NO,WKREG=R15
These examples will produce:
VFAC0026W 13.25.46 DEFINITION NOT ACCEPTED+
L R2,VFAINTV WTOPC TEXT='INTERVAL= ..... SECONDS', X NUM=4,LET=I,PREFIX=VFAC, X SUB=(DEC,(R2))
This example will produce:
VFAC0004I 08.30.00 INTERVAL= 12 SECONDS+
DCTMSG USING DCTMSG,R3 LA R3,HEADER1 LOAD ADDRESS OF HEADER1 TEXT WTOPC TEXTA=MSGLEN,PREFIX=DRCT,NUMA=MSGNUM,LETA=MSGLET, X CHAIN=YES,ENDOFM=NO WTOPC TEXTA=HEADER1,HEADER=NO, X CHAIN=YES,ENDOFM=NO * Loop for each line of text WTOPC TEXTA=LINETEXT,HEADER=NO, X SUB=(CHARA,EBW000,CHARA,(R4),CHARA,EBW004,CHARA,EBW008, X CHARA,EBW012), CHAIN=YES,ENDOFM=NO * End of line loop WTOPC TEXTA=ENDTEXT,HEADER=NO, X CHAIN=YES,ENDOFM=YES HEADER1 GENMSG NUM=1,LET=I,TEXT='DISPLAY OF ACTIVE APPLICATIONS' HEADER2 GENMSG TEXTONLY='APPL CPU SS SSU STATUS' LINETEXT GENMSG TEXTONLY='.... .. .... .... ........' ENDTEXT GENMSG TEXTONLY='END OF RCAT DISPLAY' X
This example will produce:
DRCT0001I 09.58.12 DISPLAY OF ACTIVE APPLICATIONS APPL CPU SS SSU STATUS AAAA A BSS HPN ACTIVE CLGA A BSS HPN ACTIVE CLGB B BSS HPN ACTIVE CLGC C BSS HPN ACTIVE . . . SMPB B BSS HPN ACTIVE SMPC C BSS HPN ACTIVE END OF RCAT DISPLAY
WTOPC PREFIX=CMKH,NUM=11,LET=E,ECB=NO,ROUT=(PRC,RO), X TEXT='TERMINATED E-TYPE PROGRAM', X HEADER=YES,ENDOFM=NO,WKREG=R15 * Loop for output text lines WTOPC ECB=NO,ROUT=(PRC,RO),TEXTA=DECMSG, X HEADER=NO,ENDOFM=NO,WKREG=R15 * End of text loop WTOPC ECB=NO,ROUT=(PRC,RO), X TEXT=' END OF MESSAGE CMKH0011E', X HEADER=NO,ENDOFM=YES
This example will produce:
CMKH0011E 10.16.45 TERMINATED E-TYPE PROGRAM .....message text line............... .....message text line............... .....message text line............... . . .....message text line............... .....message text line............... END OF MESSAGE CMKH0011E
WTOPC CHAIN=YES ENDOFM=YES,PAGE=NO,TEXT='DISPLAY COMPLETE'.to indicate the end of a multiple line message. PAGE=NO is used for this last WTOPC to avoid appending 'ENTER ZPAGE TO CONTINUE' to a display that is already complete. This code was taken from one of the command processors.
CSM0_REPORT DS 0H ST R15,EBW072 SAVE RETURN ADDRESS ACROSS WTOPC TM EBW080,CSM0HDR HAS THE HEADER BEEN SENT? BO CSM0SBSQ YES, SKIP OVER GEN HEADER BAS R15,CSM0_HEADER GO WRITE THE REPORT HEADER SPACE 2 CSM0SBSQ DS 0H * * WTOPC W/O HEADER AND PREFIX USED FOR ALL SUBSEQUENT DISPLAY * LINES OF NORMAL DISPLAY * WTOPC TEXTA=(R4),HEADER=NO,TIME=NO,ENDOFM=NO,CHAIN=YES, X SUB=(CHARA,RV1NAME,HEX4A,RV1SDA,CHARA,(EBW092,1), X CHARA,RV1NETID,CHARA,EBW084,CHARA,EBX084,CHARA,EBX092), X PAGE=YES,PAGESTOP=CSM0_EXIT,NEXTPAGE=CSM0_NEWHDR L R15,EBW072 RESTORE RETURN ADDRESS BR R15 RETURN TO CALLER SPACE 2 CSM0_NEWHDR DS 0H BAS R15,CSM0_HEADER GO WRITE THE REPORT HEADER L R15,EBW072 RESTORE RETURN ADDRESS BR R15 RETURN TO CALLER EJECT 1
This subroutine writes the table header and is referred to in the previous subroutine. WTOPC w/header and prefix is used on the first line of the display. None of these require the NEXTPAGE since this must be the beginning of a display. Each line must be WTOPC'd individually since WTOPC PAGE=YES counts WTOPC's not lines.
CSM0_HEADER DS 0H ST R15,EBW076 SAVE LINK REG ACROSS WTOPCS WTOPC TEXTA=CSM0MHDR,PREFIX=NALS,NUM=01,LET=I,ENDOFM=NO, X CHAIN=YES,PAGE=YES,PAGESTOP=CSM0_EXIT WTOPC TEXTA=CSM0MS01,HEADER=NO,TIME=NO,ENDOFM=NO, X CHAIN=YES,PAGE=YES,PAGESTOP=CSM0_EXIT WTOPC TEXTA=CSM0MS02,HEADER=NO,TIME=NO,ENDOFM=NO, X CHAIN=YES,PAGE=YES,PAGESTOP=CSM0_EXIT OI EBW080,CSM0HDR INDICATE HEADER SENT. L R15,EBW076 RESTORE LINK REGISTER BR R15 RETURN TO CALLER EJECT 1 *********************************************************************** * the definitions for the report headers and substitution fields. * *********************************************************************** CSM0MHDR EQU * DC AL1(CSM0MS01-CSM0MHDR-1) DC C' ' NO TEXT ON PREFIX LINE CSM0MS01 EQU * DC AL1(CSM0MS02-CSM0MS01-1) DC C' NAME SDA STATUS NET-ID CLU-NAME' DC C' CDRM-NAME TRC' CSM0MS02 EQU * DC AL1(CSM0MS03-CSM0MS02-1) DC C' ---- --- ------ ------ --------' DC C' --------- ---' CSM0MS03 EQU * DC AL1(CSM0MS04-CSM0MS03-1) DC C'........ INACTIVE' CSM0MS04 EQU * DC AL1(CSM0MS10-CSM0MS04-1) DC C'........ .... ACTIVE/.. ........ ........' DC C' ........ ...' CSM0MS10 EQU * EJECT 1