gtpp2m0b | Programming Standards |
Sending most output messages to the system operator is a simple, straightforward, uncomplicated task. For most messages, it is only necessary to point to the output parameters and text, relying on the system to do the formatting. The following macros are provided for this purpose and should be used whenever possible.
The WTOPC macro constructs a message block and provides facilities for converting binary values into EBCDIC, decimal, or hexadecimal, and for editing the message.
The GENMSG macro constructs the information that WTOPC uses to build a message. Multiple GENMSG macros can be assembled together to form message text tables.
The DCTMSG macro defines and labels entry information generated by the GENMSG macro. These labels can be used when coding a subsequent WTOPC macro.
The WTOPC macro is described in TPF General Macros and in the TPF C/C++ Language Support User's Guide. GENMSG and DCTMSG are described in more detail in TPF General Macros.
Note |
---|
If you are coding in C, do not use printf. Use the C language wtopc macro. See the TPF C/C++ Language Support User's Guide for more information. |
All characters are allowed for messages except the following:
TPF system code unconditionally translates these two characters to X'4B' (.). Control program (CP) user exit WTOP is provided for you to customize your output. See TPF System Installation Support Reference for more information about this user exit.
All messages from the system to the operator, whether reply or unsolicited, have the same basic format:
Message_ID Time_stamp Text
All messages from the system to the operator, whether reply or unsolicited, must have a unique message identifier (ID). A unique message ID is made up of a segment name, message number, and a severity code in the form aaaannnns where:
For a reply message, this represents the secondary action code of the associated command.
For an unsolicited message, this represents the issuing program or package name.
This is a decimal number from 0001 to 9999. Each message should have a unique message number.
This code is used by the operator to determine what additional action, if any, is required. The codes are:
This code is appended to all normal response message numbers.
This code indicates that additional operator action is required.
This code is appended to error messages that may require additional operator action.
This code is appended to error messages that reflect an error condition without program termination.
This code indicates that the program or function is in error and that program termination has taken place.
Message identification is made through the prefix and number only. The severity code is used only as a qualifier.
The following examples show how the message identification guidelines are used.
For command:
ZDKAT KPB
a normal reply message is:
DKAT0001I 11.35.00 KEYPT B IS PROC UNIQUE AND SS RESIDENT KEYPT B FILE ADDRESS 18480013 KEYPT B CORE ADDRESS 000CD458
For the command:
ZDKAT KPQ
an error reply message is:
DKAT0006E 11.35.00 INVALID KEYPT NAME, CHOOSE FROM A,B,C,D,E,I,M,V,0,1,2,3,4,5,6,9
The following are examples of unsolicited messages:
Note on Messages for the TPFDF Recoup Package |
---|
Message numbers in the 9000-9999 range with the RECP message identification code (ID) are reserved for the TPF Database Facility (TPFDF) product. |
A message can be identified by more than one ID, but not in the same segment; nor can an ID identify more than one message except where the subsequent message is a more detailed form of previous messages.
Some examples follow:
ABCD0001W THIS IS AN ATTENTION MESSAGE ABCD0001E THIS ATTENTION MESSAGE HAS NOW BECOME AN ERROR
The message is correct as follows:
ABCD0001W THIS IS AN ATTENTION MESSAGE ABCD0002E THIS ATTENTION MESSAGE HAS NOW BECOME AN ERROR
ABCD0010E ERROR RETRIEVING RECORD FROM FILE EFGH0010E ERROR RETRIEVING RECORD FROM FILE
ABCD0015E ERROR RETRIEVING RECORD FROM FILE ABCD0015E ERROR RETRIEVING RECORD FROM FILE BECAUSE RECORD ID WAS CORRUPTED
ABCD0015E ERROR RETRIEVING RECORD FROM FILE ABCD0015E ERROR RETRIEVING RECORD nnnn FROM FILE
A time stamp is required on all messages. The time stamp must give the value of the 24-hour local standard time clock. (Note that local standard time is subsystem unique. Some messages may require the use of a time-of-day (TOD) clock for time stamping. The time stamp immediately follows the message ID and precedes the message text as follows.
MSG ID TIME STAMP MESSAGE TEXT MCHR0050E 10.05.11 INVALID FARF ADDRESS
There are two kinds of messages: static and variable.
Static messages are those that do not contain variables. There is only one message text and only one meaning.
CANT0001I 14.52.24 ANT LOAD SUCCESSFUL
Variable messages contain parameter data. The variable data should not change the meaning or context of a message. There are various kinds of parameter data: main storage displays, tag names, program names, record IDs and numbers, time stamps, addresses, utility names, processor numbers and displays (such as from operator commands ZSTAT, ZDFPC, ZNETW D, and others).
Output requiring more than one line can be either of two formats: table displays or formatted displays. Each can also be static or variable.
Table displays are usually in tabular form and begin with headings identifying the multiple lines that follow. For example:
SYSL0002I 17.52.21 CURRENT SHUTDOWN LEVELS FOR CLASS BATCH TOTAL SHUTDOWN SHUTDOWN KEYWORD ALLOCATED LEVEL PCT-AGE CMB 258 123 48 ECB 541 259 48 FRM 2709 1300 48 IOB 2272 1090 48 SWB 1128 541 48 END OF DISPLAY
Formatted displays usually have fixed forms and contain the same number of output lines. The output lines can have a mixed style.
STAT0008I 14.51.24 SYSTEM STATUS DISPLAY IOB FRAME COMMON SWB ECB ALLOCATED 2720 6000 500 1000 3000 AVAILABLE 2703 5834 465 932 2998 ACTIVE ECBS 2 PROCESSED 0 LOW SPEED 0 ROUTED 0 CREATED 70 END OF DISPLAY
It is suggested that you use the ZPAGE function to display continuation messages. Remember that subsequent pages of a multiple-line message that are displayed after ZPAGE has been entered are considered new messages. Therefore, a header line containing the original message ID should be the first line of subsequent pages.
Formatted displays that contain no variable data are simply static displays.
MPIF0001I 14.51.24 MPIF HELP DISPLAY TRACE - USED TO TRACE ACTIVITY OF A USER, PATH OR DEVICE USER - NAME OF THE USER PATH - NAME OF THE PATH OR DEVICE ALL - TRACE ACTIVITY ON ALL PATHS STOP - STOP ACTIVE TRACE DISPLAY - DISPLAY THE IN-CORE MSRB TRACE TABLE NOLOG - DO NOT WRITE MSRB TRACE TO REAL-TIME DUMP TAPE END OF DISPLAY
The following modifications are allowed to existing message text because they will not cause breakage to existing automation procedures that follow the recommended message parsing techniques that are described in Message Parsing Techniques:
TRAC0001I TRACE MODIFY COMPLETE RC=rc
If a human readable text is used to represent the values of rc, each value must be represented by the same number of tokens.
When a new message is being considered for a segment, examine all existing messages that are issued by that segment to determine whether an applicable message already exists. If no message text exists that satisfies the requirements, a new message can be generated.
If message text exists in a segment, it must be used with the existing message ID. There should be no duplicate message texts in a segment.
Message text must depict only one meaning. If a message already exists for one purpose, but its text could be interpreted differently for another condition, a different message and message ID must be used.
Message parsing becomes extremely important in the context of automation. Console automation and test script automation (with a product such as EOCF/2) are the most relevant for the TPF system. The method of automation influences the parsing techniques used.
Techniques for parsing the message ID should be structured in such a way that they will be independent of system changes.
In EOCF/2, the message filter parses the message ID. The selected message is then passed to a user automation script. The automation script does not need to parse the ID.
The solution for parsing a message ID is to break the ID into its parts and to compare each part against the same part of each ID in a predefined set. The prefix and severity code can be compared by using string compares, while the number can be compared using a numeric comparison. This numeric comparison will ignore any leading zeros, and therefore, will allow the serial number to be expanded without the threat of reducing the effectiveness of the automation.
Parsing variables is only necessary for variable messages. Static messages are always identified by the message ID.
Either console or test script automation will have to parse the message text.
Always parse the text by using tokens (strings delimited by blanks and special characters), not by position. Tokens allow easier handling of variable length fields.