For the Database Administrator (DBA)

DBD, PSB and MFS Statements

Chapter 7: For the TM/MFS Expert

This chapter describes the IMS Option support for a variety of TM and MFS features. The chapter DBD, PSB and MFS Statements has additional information.

Some of the descriptions only require a moderate understanding of MFS and IMS/ESA TM. Others require interpretation by an expert.

7.1 MFS Input Data Set Contents

IMS Option supports a large number of FMT, MID and MOD definitions in a single input data set. The actual limit is 16,535 of any one type. IBM 3270 terminal MFS descriptions must contain the MID, MOD and FMT in the same input data set. IBM 3270 printer formats require the FMT and the MOD to be in the same input data set.

The same MOD-name cannot be used to describe more than one device type, for example, both a printer and a display device. You can set Device model to gen by selecting the Advanced page on the MFS page of the Build Settings for Project dialog box on the Project menu. In the case where the same MOD is used to send a message to a display device and a printer within the same scheduling, you must remove one of the devices from the original MFS and regenerate it with a new name. Then, change the program's ISRT call to reference the new MOD-name.

The processing sequence for MFS source data sets is:

The MIDs, MODs and FMTs are counted during the initial pass of the first-phase preprocessor. If more than one MOD is identified (but only one MID and one FMT) the first-phase preprocessor logically removes all MODs following the first. The rest of the MFSGEN proceeds normally. The first phase preprocessor is invoked again, this time removing all but the second MOD and so forth, until all of the MODs have been processed.
If more than one FMT or more than one MID is counted during the initial pass, a SCAN phase is invoked after the first phase preprocess and before the second phase preprocess. Scanning aligns the MOD selected with its FMT and aligns the MOD with its MID. The rest of the MFSGEN proceeds normally. The MOD's operands identify the selections as follows:
- FMT by the MOD's SOR operand
- MID by the MOD's NXT operand
If no NXT operand is found, the first MID in the data set is used. The SOR operand is required but the optional IGNORE operand is ignored.
If the DPAGE contains multiple physical pages, each physical page is selected and processed. This occurs after MOD selection and/or scan alignment, as needed. The last phase displays each physical page as it is processed.

7.2 MFS LPAGE/DPAGE Statements

The LPAGE and DPAGE statements are supported. See the other sections in this chapter for details on logical paging, operator paging control and multiple device pages.

The first-phase preprocessor handles the presence of LPAGE and DPAGE statements very much like the occurrence of multiple FMTs, MIDs or MODs. The presence of more than one LPAGE within a MID, more than one LPAGE in a MOD or more than one DPAGE in a FMT, triggers this support. The presence of only one LPAGE and only one DPAGE requires no special support.

If the multiple LPAGE/DPAGE condition is met, the SCAN phase is invoked just as if more than one MID, MOD or FMT was encountered. Although in this case, the first MOD/LPAGE is selected instead of just the first MOD. This LPAGE is aligned with its FMT/DPAGE using the MSG statement's SOR keyword to determine the FMT and the MOD's LPAGE statement's SOR keyword to determine the DPAGE. The MID is selected using the MOD's MSG statement's NXT operand. The MID's LPAGE statement's SOR operand is matched to the FMT/DPAGE selected. Multiple DPAGE-names are supported in the MID's LPAGE statement's SOR operand. If no NXT appeared in the MOD, the first MID is used. After this alignment, the rest of the MFSGEN proceeds normally. If more LPAGEs are present for this MOD, the scan phase is re-invoked for each MOD/LPAGE combination, with processing occurring for each set independently. When processing of all LPAGEs in the MOD is complete, control returns to the first-phase preprocessor for selection of the next MOD, if present, and its LPAGEs, if any, are processed and so forth until the entire MFS is processed.

7.3 MFS Physical Paging

Physical paging is indicated in the MFS source by use of a third positional operand on the DFLD statement's POS keyword. For example, POS=(03,14,02) to indicate a DFLD which is on line 3, column 14, on physical page number 2. One output message causes multiple physical pages (or screens) to be displayed.

Physical paging is supported for 3270 display devices only. Physical paging is not available when logical paging is also used. Logical and physical paging are mutually exclusive in IMS Option.

When an application returns control to IMS Option, the first physical page is displayed. Pressing Enter causes the next physical page to be displayed (NEXTPP equivalent). When you press Enter on the last physical page, the data from the screens is transmitted, the input message is formatted and the next transaction scheduled.

A PF key may also advance the physical page display. For all PF keys other than the ENDMPPI command, pressing the PF key causes the next physical page to be displayed. If pressed on the last screen, the screen data is transmitted for input message formatting. The ENDMPPI command terminates the screen display and begins input message formatting.

If the PF key is associated with an IMS/ESA command, such as /RCL, the command is processed when the screens are transmitted. Unless ENDMPPI is used, the value for the first PF key pressed in a series of physical pages takes effect when the input message is formatted.

7.4 Multi-segment Messages

Multi-segmented messages are defined in MFS with multiple SEG statements between the MSG (TYPE=INPUT or TYPE=OUTPUT) and corresponding MSGEND statement. The support for multi-segmented messages within IMS Option is:

Multi-segmented messages are supported for both input and output. Any number of segments may be defined for input and for output. An input message may have just one segment where the corresponding MOD may have multiple. Or, both input and output messages may be multi-segmented.
Multi-segmented messages are only supported for MFS messages and may be defined for 3270 printer and 3270 display devices
Multi-segmented messages may be used with logical or physical page input and output
MFS Input Message Edit routines are not supported for multi-segmented messages
Field exits may be used on any valid field in any of the input segments
The /FOR modname command for a MOD with multiple segments is supported only when the MID contains a single segment. If the MID contains more than one segment, the screen is formatted correctly, however, a QD status code is returned when the GN for the second input message is issued.
There is no "null" segment support. Formatting option code 2 (OPTCD=2) messages are processed as if formatting option code 1 were specified.
The upper case conversion support is dictated only by the GRAPHIC statement on the first SEG of the input message. Thus, all input segments may or may not be converted to upper case. However, there can be no mixed case for individual segments. See the section MFS ALPHA Statement for more details of upper and lower case translation.

7.5 MFS ALPHA Statement

The ALPHA statement in MFS source is supported differently in IMS Option than with IMS/ESA. Only one form is supported and it is any ALPHA statement which contains the string "abcdefghijklmnopqrstuvwxyz". When this statement is present, you can enter lower case characters in the MFS DFLD unprotected fields if the SEG statement for the input message also specifies GRAPHIC=NO. The assumption is that if you wanted to use lower case in the MFS, you would also want to use lower case in the entry fields.

IMS Option always permits any characters, including lower case, in the construction of labels and literals, whether the ALPHA statement is present or not.

7.6 MFS EQU Statement

The EQU (equate) statement is supported with the following constraints:

A maximum of 255 EQU statements may appear in a single input data set. Any EQUs exceeding the maximum are ignored
The maximum length of an equated value is 90 bytes including the imbedded double quotes but not including any "extra" outermost quotes. The length does not include any leading or trailing "=" sign.
The only statements affected by EQU are MFLD, DFLD, DPAGE and DEV statements which contain the PFK operand. PFK operand values themselves are not supported as equated values
Only one keyword, one positional parameter, one keyword value or one keyword with its value may be equated
Equate substitutions do not appear in the MFSGEN list file, if requested. EQU substitutions may be reviewed by looking at the mfs370.pre work file created by the first-phase preprocessor. Please note that this file does not contain MFS statements which are all valid: the syntax of some statements may have been changed to make the remaining phases and processes of MFSGEN easier or faster.
Concatenated equates are supported but the point of concatenation must occur at an "=" (equal sign) delimiter between a keyword and its data

Unsupported EQU example:

AYJR EQU 'ATTR=YES,JUST=R'

Supported EQU examples:

AY   EQU 'ATTR=YES'
JR   EQU 'JUST=R'
A    EQU 'ATTR'
P    EQU 'PROT'
AE   EQU 'ATTR='
EP   EQU '=PROT'
PO   EQU 'POS='
L    EQU 'LTH='

     MFLD FLD1,L.4,AY,JR
FLD1 DFLD L.4,PO.(01,03),A.EP
FLD2 DFLD L.4,PO.(02,03),AE.P
FLD3 DFLD L.4,PO.(03,03),ATTR=P

Note: The specification of A.P or AE.EP is not valid. However, IMS Option makes the substitution assuming one and only one "=" (equal sign) was present - no warning message is issued.

7.7 Logical Paging with Multiple DPAGEs

The documentation here of multiple logical paging with multiple device pages is mostly a reiteration of IMS/ESA support unless specifically noted otherwise. As the terminology used for this area of MFS is not always understood, the best way to document our supported features is to describe it by example.

Multiple logical paging with multiple device paging is indicated in the MFS source statements by the presence of a COND=(mfldlabel,relational operator,value) operand on the MOD's LPAGE statement. The "mfldlabel" may also be specified as an integer value indicating an offset in the MOD. The application program indicates which screen (actually, which device page) is to be displayed by both the MOD-name parameter and the COND value. The application program may insert more than one screen in this manner, although only the first ISRT call is permitted to have a MOD-name parameter. IMS Option does not support multiple logical paging using different MOD-names.

Sample MFS source:

FMT1   FMT
DPAGE1 DPAGE  ...
       DFLD   ...
       DFLD   ...
DPAGE2 DPAGE  ...
       DFLD   ...
       FMTEND

MOD1   MSG TYPE=OUTPUT,
             SOR=(FMT1,IGNORE),NXT=MID1
       LPAGE SOR=(DPAGE1),
             COND=(PAGENO,=,'01')
       SEG
       MFLD  ...
PAGENO MFLD LTH=2
       LPAGE SOR=(DPAGE2),
             COND=(PAGENO,=,'02')
       SEG
       MFLD  ...
PAGENO MFLD  LTH=2
       MSGEND

       MSG TYPE=INPUT,
             SOR=(FMT1),NXT=MOD1,...
       LPAGE SOR=(DPAGE1)
       SEG
       MFLD  ...
       MFLD  ...
       LPAGE SOR=(DPAGE2)
       SEG
       MFLD  ...
       MFLD  ...
       MSGEND

From this sample MFS, the first insert call by a COBOL application would appear something like this:

MOVE 'MOD1'   TO MOD-NAME.
MOVE '01'     TO MOD-PAGENO.
CALL 'CBLTDLI' USING ISRT
                     IO-PCB
                     MOD-AREA
                     MOD-NAME.

Although subsequent insert calls are not required, they would appear something like this:

MOVE '02'     TO MOD-PAGENO.
CALL 'CBLTDLI' USING ISRT
                     IO-PCB
                     MOD-AREA.

The page numbers do not have to be inserted in the order they appear in the MOD or the FMT. They can be in any order, repeated, alternated or in any other combination. The only requirement is that after the first insert call, the MOD-name parameter is omitted.

If the COND value provided in the MOD's I/O area does not match any COND value specified in the MFS MOD LPAGE statement, the last LPAGE in the MOD is used. If a MOD contains only one LPAGE with a COND value, it has no meaning. The IMS Option MFSGEN process ignores these LPAGEs as they always cause the same screen to be inserted and no special processing is required.

7.8 Operator Paging Control

Operator paging control consists of the commands and mechanisms by which the terminal operator controls multi-paged output. This operator control facility is used whenever logical paging is used, whether for a single DPAGE or for multiple DPAGEs.

The paging control is indicated by the use of:

Command	Description
=nnnn	Indicates the specific page number to be displayed next. An "nnnn" value of 1 causes the first page of the set to be displayed
=+nnnn	Indicates the number of the page to be displayed as a number of pages forward from the current page. A value of +2, for example, would cause the second page, after the current displayed page, to be displayed next.
=-nnnn	The same as "+" except the movement is backward instead of forward
=L	Indicates the last page is displayed

These control statements can be entered from one of the following:

A cleared screen (Alt+F2 clears the screen in IMS Option)
The first MID MFLD's DFLD
A PF key which translates into one of the above values (assuming the PF key value also appears as the first MFLD in the MID)

To use the cleared screen technique, press Alt+F2 from an MFS screen, type the paging command and press Enter to process the page request.

7.9 /FOR Command and LPAGE

When a /FOR command is issued for a MOD which contains multiple LPAGEs, the last LPAGE in the MOD determines which DPAGE is displayed. With IMS/ESA, it is possible under some constraints, to issue a /FOR command with the COND value following the MOD-name. For example, /FOR MOD1 01. This is not supported by IMS Option.

7.10 MFS Field Exits

MFS input MFLD (MID) field exits can be re-written from Assembler to COBOL or the Assembler routines from IMS/ESA may be used if you have Micro Focus 370. You can use the TM/MFS configuration option Invoke input message edit routines to specify whether COBOL or Assembler routines should be called. To access this, select the TM/MFS page on the IMS System Properties dialog box. The default is unselected, with field exits not invoked.

Note: You can access the IMS System Properties dialog box by selecting the IMS View of the project and right-clicking IMS System. Then click Properties.

If you select COBOL, IMS Option calls the exit using standard COBOL linkage conventions. The calling parameters are otherwise the same as on IMS/ESA. A sample COBOL field exit is provided with IMS Option and is named dfsme000.cbl. This program has comments in it which further describe the use of COBOL field exits. When you add this source to your project and compile it, the load module is added to the Project's default Load Library folder defined in the Workgroup tab.

If you select Assembler, you must also preprocess, assemble and link the ims2asm.mlc program provided with IMS Option. The IMS2ASM routine is a "glue" module and converts the COBOL standard linkage parameters from IMS Option into the non-standard form which IMS/ESA uses for Assembler. See the ims2asm.mlc program for further details.

The naming convention is the same as IMS/ESA. The field exit program name is always "DFSME" followed by the field exit number expressed as a three digit decimal number. For example, for field exit number "zero", the name would be DFSME000.

The field exit can be debugged as any other application program. When a transaction program issues the GU or GN for the input message, the field exit is invoked and is debugged if it has been prepared for debugging. To do this:

Select the Files tab
Select the COBOL folder on the left-hand pane of the project window
Right-click on Dfsme000.cbl on the right-hand pane of the project window and select Build Settings for Dfsme000.cbl from the popup menu
On the General page check Create debug information
Click OK

7.11 MFS Input Message Segment Edit Routines

IMS Option now supports MFS input message segment edit routines (DFSMExxx). This support is similar to the existing support of MFS field exit routines but is limited to single segment messages. MFS segment and field exits can not be configured independently. As in the existing field exit support, there is no support for IMS callable services and no emulation of IMS control blocks.

These edit routines can be written in COBOL or Assembler:

For Assembler, you must include the supplied module ims2asm.mlc with the application for proper emulation of the non-standard IMS/ESA linkage parameters
For COBOL, there is a sample program dfsme127.cbl which demonstrates a COBOL exit routine. Configuration is the same as for MFS field exits.

The exit language configuration option specifies the exit language and allows exit routines to be disabled. You can find this option on the TM/MFS page of the IMS System Properties dialog box.

7.12 FILL=NULL Support

FILL=NULL can be specified on any MFLD. This support is provided with single-segment and multi-segment messages, with or without logical paging.

7.12.1 Restrictions

There are two restrictions with FILL=NULL. They are:

When physical paging is used, FILL=NULL is only supported for the PF Key field. This physical paging restriction is only in effect when you define a page number greater than 1 in any DFLD. For example, DFLD 'TEST LITERAL',POS=(1,2,3) where '3' indicates the third physical page.
When compression of MFLDs results in an empty segment, the segment is returned with a length of five containing just one byte of data. It is not discarded.

For the Database Administrator (DBA)

DBD, PSB and MFS Statements