MFS examples

One way to understand the relationship between the MFS control blocks is to look at a message from the time a user enters it at the terminal to the time the application program processes the message and sends a reply back to the terminal. Though MFS can be used with both display terminals and printer devices, for clarity in this example, a display terminal is being used.

The following figure shows the relationships between the MFS control blocks.

begin figure description - This figure is described in the surrounding text. end figure description

Looking at payroll records

Suppose your installation has a message processing program used to view employee payroll records. From a display terminal, issue the IMS format command (/FORMAT), and the MOD name. This formats the screen in the way defined by the MOD written by the MFS programmer. When you enter the MOD name, the screen contains only literals and no output data from the application program. At this stage, no application program is involved. (For more information about /FORMAT, see IMS Version 15.2 Commands, Volume 1: IMS Commands A-M.)

In this example, suppose the name of the MOD that formats the screen for this application is PAYDAY. Enter this command:

/FORMAT PAYDAY

IMS locates the MFS MOD control block with the name PAYDAY and arranges the screen in the format defined by the DOF.

The following figure shows how this screen looks.

Figure 2. PAYDAY screen, formatted by DOF

                                  *EMPLOYEE PAYROLL*
                                  ******************
 
 
                 FIRST NAME:                              LAST NAME:
                 EMPLOYEE NO:
 
 
 
                 INPUT:

The DOF defines a terminal format that asks you to give the employee's name and employee number. PAYUP is the transaction code associated with the application that processes this information. When you enter the MOD name, the transaction code is included in the first screen format displayed. This means that you do not need to know the name of the program that processes the data; you only need the name of the MOD that formats the screen.

After the screen format is displayed, you can enter the information. There are four stages to sending a message to the program and receiving the reply:

Enter the information at the terminal. For this example, enter the prompted information.

The following figure shows how this screen looks after information is entered.

Figure 3. PAYDAY screen, with filled input fields

                                   *EMPLOYEE PAYROLL*
                                   ******************
 
 
                  FIRST NAME: Joe                        LAST NAME: Blutzen
                  EMPLOYEE NO: 60249
 
 
 
                  INPUT:

When IMS receives this data, MFS uses the DIF and the MID control blocks to translate the data from the way it was entered on the terminal screen to the way that the application program is expecting to receive it. The DIF control block tells MFS the format of the data to come in from the terminal. The MID control block tells MFS how the application program expects to receive the data. When the application program issues a message call, IMS places the translated message in the program's I/O area.
When the application receives the message in its I/O area, the message looks like this:
```
PAYUP JOE BLUTZEN 60249
```
PAYUP is the transaction code. The name of the logical terminal does not appear in the message itself; IMS places it in the first field of the I/O PCB.
The application program processes the message, including any required database access, and builds the output message in the application program's I/O area. After retrieving the information from the database, the program builds the output message segment for the employee, with social security and rate of pay information. The application program's I/O area contains:
```
LLZZJOE BLUTZEN 60249532596381150.00
```
The LL is a 2-byte field in MFS messages that indicates the length of the field. How the LL field is defined depends on what programming language used to write the application program. For the AIBTDLI, ASMTDLI, CEETDLI, or PASTDLI interfaces, the LL field must be defined as a binary half word. For the PLITDLI interface, the LL field must be defined as a binary fullword. The value provided in the PLITDLI interface must represent the actual segment length minus 2 bytes.

The ZZ is a 2-byte length field in MFS messages that contains the MFS formatting option that is being used to format the messages to and from the application program. MFS options are discussed in further detail in the topic "Input Message Formatting Options" in IMS Version 15.2 Application Programming APIs.
When the application program sends the message back to the terminal, MFS translates the message again, this time from the application program format to the format in which the terminal expects the data.
The MOD tells MFS the format that the message will be in when it comes from the application program's I/O area. The DOF tells MFS how the message is supposed to look on the terminal screen. MFS translates the message and IMS displays the translated message on the terminal screen.

The following figure shows how the screen looks.
Figure 4. PAYDAY screen, output formatted by DOF and displayed
```
                                  *EMPLOYEE PAYROLL*
                                  ******************
 
 
                FIRST NAME: Joe                        LAST NAME: Blutzen
                EMPLOYEE NO: 60249
                SOC SEC NO: 532-59-6381
                RATE OF PAY: $150.00
 
 
                INPUT:
 
 
```

Listing a subset of employees

Suppose you have an MPP that answers this request:

List the employees who have the skill ENGINEER with a skill level of 3. List only those employees who have been with the firm for at least 4 years.

To enter the request from a display terminal, issue the format command (/FORMAT) and the MOD name. This formats the screen in the way defined by the MOD you supply. When you enter the MOD name, the screen contains only literals and no output data from an application program. At this stage, an MPP is not involved. Suppose the name of the MOD that formats the screen for this request is LE, for locate employee. Enter this:

/FORMAT LE

IMS locates the MFS MOD control block with the name LE and arranges your screen in the format defined by the DOF. Your screen then looks like this:

SKILL
LEVEL
YEARS
      LOCEMP

The DOF defines a terminal format that asks you to qualify your request for an employee by giving the skill, level, and number of years of service of the employee you want. LOCEMP is the transaction code that is associated with the MPP that can process this request. When you enter the MOD name, the transaction code is included in the first screen format that is displayed for you. This means that you do not need the name of the program that processes your request; you only need the name of the MOD that formats the screen.

After the screen format is displayed, you can enter your request. There are four stages in sending a message to the program and receiving the reply.

Enter the information at the terminal. In this example, enter the values of the qualifications that IMS has given you on the screen: the skill is eng (engineer), the skill level is 3, and the number of years with the firm is 4.
After you enter your request, your screen contains this data:
```
SKILL ENG
LEVEL 3
YEARS 4
      LOCEMP
```
When IMS receives this data, MFS uses the DIF and the MID control blocks to translate the data from the way you entered it on the terminal screen to the way that the application program is expecting to receive it. The DIF control block tells MFS how the data is going to come in from the terminal. The MID control block tells MFS how the application program is expecting to receive the data. When the application program issues a GU call to the I/O PCB, IMS places the translated message in the program's I/O area.
When the MPP receives the message in its I/O area, the message looks like this:
LOCEMP ENG0304

LOCEMP is the transaction code. The name of the logical terminal does not appear in the message itself; IMS places it in the first field of the I/O PCB.
The MPP processes the message, including any required database access, and builds the output message in the MPP's I/O area.
Suppose more than one employee meets these qualifications. The MPP can use one message segment for each employee. After retrieving the information from the database, the program builds the output message segment for the first employee. The program's I/O area contains:
```
LLZZJONES,CE   3294
```
When the program sends the second segment, the I/O area contains:
```
LLZZBAKER,KT   4105
```
When the application program sends the message back to the terminal, MFS translates the message again, this time from the application program format to the format in which the terminal expects the data.
The MOD tells MFS the format that the message will be in when it comes from the application program's I/O area. The DOF tells MFS how the message is supposed to look on the terminal screen. MFS translates the message and IMS displays the translated message on the terminal screen. The screen then contains the following data:
```
SKILL    ENG
NAME     NO
JONES,CE 3294
BAKER,KT 4105
```