Dan Yee, IBM TPF Development

At the Spring 2001 TPF Users Group (TPFUG) meeting in Toronto, Canada, the TPF development lab announced that changes were being made to the current TPF output message standard. Before I go into the details of the new standard, I think you might want to know more about the history of the TPF output message standard.

History

During the late 1980s, TPF supported three releases: TPF 2.3, 2.4, and 3.1. At that time, the issue to standardize TPF output messages came about as a result of the increased use of automated operations at various customer sites. Several other IBM operating systems were already being used in an automated operations environment at these customer locations. At the same time, several other developments were occurring:

• The IBM corporation was making a proposal to standardize output messages issued from its mainframe systems.
• TPF 4.1 was being developed.
• TPF was developing its own automated operations program, later to be known as EOCF/2.

The first problem the committee faced was the format of the message ID, which precedes the message text and is intended to uniquely identify every output message displayed. Many output messages did not have standard message IDs. If an output message contained a unique message ID, the message ID consisted of a 4-character component name and a 2-digit number associated with the component name.

While developing the new TPF 4.1 code, TPF programmers were confronted with a problem. If a new message needed to be added to a component and there were already 99 messages defined for that component, what message ID should be used for the new message? The message ID needed to be unique so that automated operations programs could distinguish the new message from old messages with the same component ID. Developers working on IPLB, for example, chose to insert a letter into the 2-digit number field to make all new IPLB messages unique.

The TPF Standards Committee also had to determine what had to be done if an existing message needed to be changed. When is a new message ID required and when is it better to leave the message ID unchanged?

As a result of the first problem that I described, a proposal was made to increase the size of the 2-digit number in the message ID to 4 digits for TPF 4.1. This change to the existing output message standard occurred too late to change the new IPLB messages that were added for TPF 4.1. Like other instances in which a standard is changed in the middle of development, the change was "grandfathered" to exclude messages that had already been changed for TPF 4.1. Other old messages were also exempt from the new standard, such as various non-SNA communications line messages.

The next step for the TPF Standards Committee was to design a proposal for the new output message standard. This new proposal was presented at the Spring 1993 TPF Users Group meeting in Seattle, Washington. The proposal consisted of the following:

• A definition of static and variable data
• A standard for changing output messages
• Rules for delimiting messages
• Error processing with multiline messages.

Meanwhile, the IBM Corporate Standard for output messages, TPF 4.1, and EOCF/2 were all completed in the mid-1990s. EOCF/2 was developed on the basis of the new TPF output message standard. TPF customers modified their automation programs to accommodate the new output message standard. Though the TPF output message standard was based on the IBM Corporate Standard, it was not identical. As TPF began shipping a large amount of TPF 4.1 code in 6-month cycles, the TPF output message standard became an issue once again.

Problems with the TPF Output Message Standard

The TPF lab had most of its problems with the "Modifying Existing Messages" section in Chapter 2 of TPF 4.1 Programming Standards. The section stated, "If modifications are made to an existing message text where fields are added or deleted, format is changed, or field position is changed, a new message ID must be defined." During the Spring of 1996, several groups of developers questioned this standard as it was written. What if a single token needed to be changed? What about typographical, grammatical, or other errors with the text? Do you need to get a new message ID in those cases?

The TPF Standards Committee met in June 1996 to discuss modifying Chapter 2 to clarify the section about modifying output messages. The committee added the following wording to that section:

"Note that this also applies to fixing such things as typographical or grammatical errors. Basically, if you modify an existing message in any way, you must obsolete the existing message ID and define a new message ID."

A note was also added that stated the following:

"TPF will not take APARs for typographical, grammatical, and similar type errors in fixed text messages."

These changes may have put to rest questions regarding trivial changes to output messages. However, the section, as written, seemed to encourage TPF developers to obtain new message IDs whenever they needed to change an existing message. If a new message ID was created every time an output message was changed, automation programs installed at customer sites had the potential to break.

During the first half of the year 2000, the TPF Standards Committee met to review TPF Programming Standards. The committee came across the section about modifying output messages in Chapter 2 and proposed changing the TPF output message standard to the IBM Corporate Standard. The following is how the committee wrote up the proposal:

• Allow modifications to text as specified in the IBM Corporate Message Standard section 6.5.3.


Modification to Text: The following modifications are allowed to existing message text since they will not cause breakage to existing automation procedures:

• Message text with no substitutable data fields may be changed as necessary provided the meaning of the message text does not change. A substitutable data field(s) may be added to the message text; however, any subsequent change must follow the next rule.
• Message text with substitutable data fields may be changed as long as the number of tokens needed to represent the message text and the position of tokens representing substitutable data fields in the message text does not change. In addition, the following changes may be made to these messages:
• Additional values may be added to an existing substitutable data field.
• The length of substitutable data fields may change.
• New substitutable data fields may be added to the end of the message text provided the meaning of the original message does not change.

• It reduces risk of outages caused by missing message ID changes.
• It reduces rework to automation caused by unnecessary message ID churn.

The committee also came across the "Message Parsing Techniques" section in Chapter 2 of TPF Programming Standards. This section discussed using the following parsing techniques to identify static and variable output messages:

• Parsing static messages by message ID
• Parsing variable messages by using tokens.

Although these parsing techniques were the ones recommended by TPF, no one on the committee knew how many TPF customers were following them. The committee also realized that changing the TPF standard for output messages could impact automation scripts installed at customer sites, so they decided to obtain automation information from TPF customers. The committee wrote up questions to be included on a survey form that was distributed at the Spring 2000 TPF Users Group meeting in Las Vegas, Nevada.

TPF Surveys Customers

At the TPFUG meeting that Spring, an Information Development Customer Survey form was distributed to those in attendance. The survey contained various questions associated with the current TPF publications. Included in the survey were the following two questions related to message automation.

In your work environment, do you:

• Parse messages that contain only static text instead of using the message ID to identify the message
• Rely on column-dependent text instead of parsing the message into tokens to extract information.

Space was provided on the form for write-in comments related to these two questions.

A total of 15 customers provided information about their automation procedures. Following are the results from the survey:

• Ten customers stated that they parse static messages and rely on column data.
• Three customers stated No to both questions.
• Two customers parse static messages, but do not perform any column comparisons.

During the summer of 2000, the TPF Standards Committee met to discuss the results from the TPFUG meeting. To the committee, some write-in comments from the survey were revealing:

• "It's very annoying when the message IDs change for no obvious reason. We need clear indications when this happens."
• "We do not feel IBM has provided a clear direction for this in the past."

Other comments indicated that customers parse the message ID and the message text to identify messages. Another interesting discovery from the survey is that most customers use column comparisons instead of tokens to parse variable messages.

Confronted with this conflicting data, the committee decided to go ahead and implement the new proposal because it would, in the long run, help TPF customers to avoid outages as a result of inappropriate message ID changes. The committee also felt that most customers would modify their automation programs once TPF clarified its output message standard. As a result, the new output message standard was announced at the Spring 2001 TPF Users Group meeting in Toronto, Canada. The new standard goes into effect with PUT 15.

Examples

To help you understand the ramifications of the new output message standard, here are a few examples.

• In the following example, a new token is added to the DSYS0002I output message:

Before:

DSYS0002I 23:07:20 THE SYSTEM IS IN RESTART

After:

DSYS0002I 23:07:20 THE TPF SYSTEM IS IN RESTART

A new message ID would not be required in this case because DSYS0002I is a static message.

According to the new TPF output message standard, a new message ID is not required for a static message if text added to the message does not change its meaning.

• In the following example, a new token is added to the DSYS0001I output message:

Before:

DSYS0001I 23.07.20 THE SYSTEM IS IN 1052 STATE+

After:

DSYS0001I 23.07.20 THE TPF SYSTEM IS IN 1052 STATE+

A new message ID would be required in this case because DSYS0001I is a variable message and the position of a substitutable data field in the message changed. The state of the system is the substitutable data field in the example, so an automation program scanning for the 1052 token would not find it in the changed message.

• In the following example, a substitutable data field is added to the end of a static message:

Before:

TRAC0085I 23.09.11 TRACE MODIFY COMPLETE

After:

TRAC0085I 23.09.11 TRACE MODIFY COMPLETE RC=rc

A new message ID would not be required in this case because a new substitutable data was added to the end of the message and the meaning of the original message did not change.

Summary

The new TPF output message standard is designed to reduce the number of new message IDs created as a result of changes to existing messages. It is also designed to reduce the number of outages at customer sites caused by unnecessary changes to the message ID. However, the new standard will be most effective if your automation programs:

• Parse static messages by message ID
• Parse variable messages by tokens.

If your automation programs do not use these parsing techniques, consider changing them to use these techniques as recommended in TPF Programming Standards.

As this article indicates, TPF has a come a long way in the area of output message standards. We hope that you all agree that this change is a step in the right direction.

For more information about TPF programming standards, including the current TPF output message standard, see TPF Programming Standards, SH31-0165. When the PUT 15 version of this document is available, the new output message standard will be included. You can also link to this document from the TPF Web site at http://www.ibm.com/tpf/pubs/tpfpubs.htm.

Second Quarter 2001 - Table of Contents