gtpp2m0bProgramming Standards

Messages

Message Generation

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.

WTOPC
Edit and send system message

The WTOPC macro constructs a message block and provides facilities for converting binary values into EBCDIC, decimal, or hexadecimal, and for editing the message.

GENMSG
Generate message table for WTOPC

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.

DCTMSG
Define GENMSG entry

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.

Character Set

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.

Message Format

All messages from the system to the operator, whether reply or unsolicited, have the same basic format:

     Message_ID Time_stamp Text

Message Identification

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:

aaaa
Message prefix

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.

nnnn
Message number

This is a decimal number from 0001 to 9999. Each message should have a unique message number.

s
Severity code

This code is used by the operator to determine what additional action, if any, is required. The codes are:

 I 
Information only

This code is appended to all normal response message numbers.

 A 
Action required

This code indicates that additional operator action is required.

 W 
Attention

This code is appended to error messages that may require additional operator action.

 E 
Error

This code is appended to error messages that reflect an error condition without program termination.

 T 
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.

Message Examples

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.

Message ID Uniqueness

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:

Time Stamp

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

Message Text

There are two kinds of messages: static and variable.

Static Messages

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

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).

Multiple Line Messages

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

Conventions for Multiple-Line Messages

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

Modifying Existing Messages

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:

Defining New Messages

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 Techniques

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.