MFS input message formats

When you define the fields that make up a message segment, you give MFS information such as:

• The field length
• The fill character used when the length of the input data is less than the length defined for the field
• Whether the data in the field is left-justified or right-justified
• If the field is truncated, whether it is truncated on the left or right

The order and length of these fields within the message segment depends on the MFS option that your program is using. You specify the MFS option in the MID. The decision of which option to use for an application program is based on:

• How complex the input data is
• How much the input data varies
• The language the application program is written in
• The complexity of the application program
• Performance factors

The Z2 field in MFS messages contains the MFS formatting option being used to format the messages to and from your program. If something is wrong in the way that IMS TM returns the messages to your I/O area, and you suspect that the problem might be with the MFS option used, you can check this field to see if IMS TM is using the correct option. A X'00' in this field means that MFS did not format the message at all.

One way to understand how each of the MFS options formats your input and output messages is to look at examples of each option.

Example: Suppose that you have defined the four message segments shown in the following table. Each of the segments contains a 2-byte length field and a 2-byte ZZ field. The first segment contains the transaction code that the person at the terminal entered to invoke the application program. The number of bytes defined for each field appears below the name of the field in the figure.

When you use the PLITDLI interface, you must define the length field as a binary fullword, LLLL. When you use the AIBTDLI, ASMTDLI, CBLTDLI, CEETDLI, CTDLI, or PASTDLI interfaces, you must define the length field as a halfword, LL. The value provided by the PL/I application program must represent the actual segment length minus 2 bytes. For example, if the output text is 10 bytes, then the value of the fullword LLLL is 14 and is the sum of the length of LLLL (4 bytes - 2 bytes) + Z1 (1 byte) + Z2 (1 byte) + TEXT (10 bytes).

For these examples, assume that:

• The transaction code is defined in the MID as a literal.
• All of the fields are left-justified.
• The fill character is defined as a blank. When the length of the data in a field is less than the length that has been defined for that field, MFS pads the field with fill characters. Fill characters can be:
  • Blanks
  • An EBCDIC character
  • An EBCDIC graphic character
  • A null, specified as X'3F'

  When you specify that the fill character is to be a null, MFS compresses the field to the length of the data if that length is less than the field length.

  The fields for segment 4 of the message in the previous table are arranged on the terminal screen in the format shown in the following figure.

  Example: Assume the person enters the name of a patient, and the charges and payments associated with that patient.

MFS provides three options for message formatting.

MFS option 1

Use this option when the program receives and transmits most of the fields in the message segments. The way that option 1 formats messages depends on whether you have defined a null as the fill character for any of the fields in the segment.

If none of the fields in the message were defined as having a fill character of null:

• The program receives all the segments in the message.
• Each segment is the length that was specified for it in the MID.
• Each segment contains all its fields.
• Each field contains data, data and fill characters, or all fill characters.

The following table shows the Option 1 Format of segments received by the application program.

The message format for option 1 output messages is the same as the input message format. The program builds output messages in an I/O area in the format shown for segment 4 in the previous figure. The program can truncate or omit fields in one of two ways:

• Inserting a short segment
• Placing a null character in the field

If one or more of the fields are defined as having a null fill character, the message is different. In this case, the message has these characteristics:

• If a field has been defined as having a fill character of null and the terminal offers not data, the field is eliminated from the message segment.
• If all of the fields in a segment have a null fill character and none of the fields contains any literals, the segment is eliminated from the message.
• If only some of the fields in a segment have a null fill character, any field containing nulls is eliminated from the segment. The relative positions of the fields remaining within the segments are changed.
• When the length of the data that is received from the originating terminal is less than the length that is been defined for the field, the field is truncated to the length of the data.

MFS option 2

Use this option when the program processes multisegment messages where most of the fields are transmitted but some of the segments are omitted. Option 2 formats messages in the same way that option 1 does, unless the segment contains no input data from the terminal after IMS TM has removed the literals. If this is true, and if no additional segments in the message contain input data from the terminal, IMS TM ends the message. The last segment that the program receives is the last segment that contains input data from the terminal.

Sometimes a segment that does not have any input data from the terminal is followed by segments that do contain input data from the terminal. When this happens, MFS gives the program the length field and the Z fields for the segment, followed by a 1-byte field containing X'3F'. This indicates to the program that this is a null segment.

Segment 2 in the previous table contains only a X'3F' because that segment is null, but Segment 3 contains data. This message does not contain a segment 4 because it is null.

MFS option 3

Use this option when the program receives and transmits only a few of the fields within a segment. When you use option 3, the program receives only those fields that have been received from the terminal. The program receives only segments that contain fields received from the originating terminal. Segments and fields can be of variable length if you have defined option 3 as having a null fill character.

A segment in an option 3 message is identified by its relative segment number—in other words, what position in the message it occupies. The fields within a segment are identified by their offset count within the segment.

Example: The NAME field in segment 1 is (MCROSSbbbb). The value 17 is the sum of the lengths of the fields preceding the NAME field and includes an 8-byte transaction code and a 5-byte field of blanks. It does not include the 2-byte relative segment number field (field A in the following table), the 2-byte length field (field B), or the 2-byte relative offset field (field C).

Option 3 messages do not contain literals defined in the MID. This means that the transaction code is removed from the message, except during a conversation. If the transaction that the program is processing is a conversational transaction, the transaction code is not removed from the message. The transaction code still appears in the scratchpad area (SPA).

Each segment the program receives contains the relative number of this segment in the message (field A in the following table). In addition, each data field within the segment is preceded by two fields:

• A 2-byte length field (B). Including the length field itself, the 2-byte relative field offset, and the data in the field.
• A 2-byte relative field offset (C), giving the field's position in the segment as defined in the MID.

These two fields are followed by the data field. MFS includes these fields for each field that is returned to the application program.

Notes to the previous table:

• The fields marked A contain the relative segment number. This number gives the segment's position within the message.
• The fields marked B contain the field length. This length is the sum of the lengths of B field (2 bytes) + C field (2 bytes) + D field (the length of the data).
• The fields marked C contain the relative field offset. This gives each field's position within the segment.
• The fields marked D contain the data from the terminal. In this example, the fill character was defined as blank, so the data field is always its defined length. IMS TM does not truncate it. If you define the fill character as null, the lengths of the data fields can differ from the lengths defined for them in the segment. With a null fill character, if the length of the data from the terminal is less than the length defined for the field, IMS TM truncates the field to the length of the data. Using a null fill with option 3 reduces the space required for the message even further.