IMS DC PROGRAMMING

01/08/2004

Page 1/ 115

IMS DC PROGRAMMING

01/08/2004

Page 2/ 115

CONTENTS
IMS Online Environment System Definitions Application Program Structure Introduction to Message Format Service IMS Online Coding BTS IMS Commands Project work

IMS DC PROGRAMMING

01/08/2004

Page 3/ 115

IMS Online Environment

System Flow

BACK

The general flow of an IMS online system can be described in the following way: An operator at a 3278 terminal enters data and presses the ENTER key. The IMS online control region retrieves the data and determines the types of message. If it is an operator command, IMS responds to the command. If it is a message switch, the message is sent to the logical device. If there is a valid transaction code in the first eight characters, the message is placed in the message queue to wait for processing. The application program (associated with the transaction code contained in the first eight characters of the message waiting to be processed) is scheduled to execute in a message processing region as soon as a region becomes available. The Message Processing Program (MPP) retrieves the message from the queue and processes it. The processed data, along with other information, is put back into the queue by the MPP. The IMS control region takes the data from the queue and sends it back to the originating device.

Message Processing
A message is data transmitted from a device to a program, or a device to another device, or a device to IMS. There are three types of messages that can be sent to IMS. The first one to eight characters of the message determines which type is being sent. If the character of the input message is a slash (/), IMS will interpret the message as an operator command. The operator command and any specified keywords should be followed by a period (.) to tell IMS where it ends. If the message begins with one to eight alphanumeric characters and can be found in the logical terminal (LTERM) code reference table by IMS, it is a message switch. The LTERM code must be followed by a space to tell IMS where the code ends. The message will be sent directly to the physical device associated with the specified LTERM. This is a method of sending messages between devices without the use of an application program. If the message begins with one to eight alphanumeric characters and can be found in the transaction code reference table, the message is for an application program. The transaction code must be followed by a space to tell IMS where the code ends. This type of message is also called a transaction message.

IMS DC PROGRAMMING

01/08/2004

Page 4/ 115

Each transaction and its associated application program must be defined to the IMS online system. This definition takes place in the IMS system generation. The transaction code is logically associated with a Program Specification Block (PSB) and an application program load module name, which the online system assumes have the same name. Typically, there is a one-to-one relationship between a transaction and an application program; however, it is possible to have many transactions associated with a single program. The application program can always find out from the first eight characters of the input message the transaction code that caused it to be invoked. Conceivably, a program can be coded to behave in different ways depending on the transaction code that caused the invocation. Figure 1 shows various examples of message.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------/FORMAT CT70000M. (Operator command = /FORMAT ) WRDT0232 Good Morning CT7POLP1 100001 (LTERM code = WRDT0232 ) (Tran code = CT7POLP1 )

Message Examples Figure 1 Note: A message cannot exceed 32767 bytes in length.

Message Scheduling
The message scheduling facility of the IMS online environment controls the processing of messages. Because the system handles hundreds of data requests from clients, and the resources available to process these requests is limited, IMS message scheduling uses the concept of message queuing. When several transaction - oriented messages are received by the IMS control region, it must determine how to process them. An efficient processing sequence is implemented, with the following three factors influencing the behavior: Class - Determines which region will execute the application program associated with the transaction code. Priority - Assigns the level of importance with a range of 0 through 14.

IMS DC PROGRAMMING

01/08/2004

Page 5/ 115

Process Limit Count (PLC) - Controls the frequency of the processing selection process. Values range from 0 through 65535. (65535 is the default). Take a look at each of these factors and see how they affect our transaction-oriented message process.

Class
Each message region and transaction is assigned a class or classes. Once a transaction has been selected for processing, it must wait until an appropriate message region becomes available. Once a transaction has been selected, and a message region that can process the transaction is available, IMS will bring a copy of the load module into the region to begin executing it.

Priority
When a transaction is defined to the IMS environment through the IMS SYSGEN, it is assigned a processing priority. The priority values of a transaction range from 0 through 14. A priority of 0 means that the transaction cannot be scheduled automatically. The highest priority is 14. If one is not assigned, the default is 1. The priority is broken down into two parts. Normal - The most frequently used priority.

Limited - Used during those times a higher priority is needed. To trigger this priority into action, a limit count is assigned. As messages with the same transaction code accumulate, waiting for processing, IMS keeps track of how many there are. When the number of waiting messages reaches the limit count, IMS assigns a limit priority. The limit count has a maximum value (also the default value) of 65535. Once a transaction has been assigned a limit priority, it remains in effect until the number of waiting messages of that transaction type returns to zero. The IMS scheduling process looks at all the messages waiting to be processed and selects those with the highest priority. Once a transaction has been selected, a message region must be available that can execute the class to which the transaction has been assigned. For example: Transaction XYZ has a normal priority of seven. It also has a limit priority of 10, which is assigned when the limit count reaches 100. When the number of messages waiting to be processed reaches 100, IMS reassigns the selection priority to 10. As more XYZ messages are received, they are all reassigned the new priority, which remains until all of the XYZ messages have been processed.

IMS DC PROGRAMMING

01/08/2004

Page 6/ 115

Process Limit Count

Although the CPUs are getting faster at executing instructions, the physical I/O bringing in a load module from the library to the IMS dependent region is still time consuming. In order to allow an MPP to process more than one message during the scheduling of the load module, IMS provides for the use of the Process Limit Count (PLC). The PLC is a parameter placed on the transaction macro. It is used to define the transaction code that specifies the number of messages that can be processed by an MPP before IMS must free up the region and perform the scheduling process again. A PLC is important in an IMS environment where many clients are using the same transaction. Because this means the program can process multiple unrelated messages, the program logic must be set up to process each message independently. 1. All working storage must be reinitialized before a program starts to process a message. 2. If a loop is used to process more than one message, all working storage must be reinitialized upon reaching the top to the process loop. This method of coding a program so that each message is treated independently is called making the program serially reusable. If the PLC is ever set to more than one, the program logic must be reusable. Since the PLC can be altered dynamically and in a new system, always code an MPP to be serially reusable.
3.

Additional System Requirements

We have already mentioned several things that must be done in an IMS environment before it can begin processing messages. In addition to defining the transaction codes, you must define to IMS any LTERM codes and databases. All resources used by IMS must be defined prior to their use.

Message Formatting
When a message is received in the IMS online environment, it determines the type of message and invokes one of the common services such as MFS. MFS is a facility that reformats messages according to control blocks. The formatting of messages is done by the MFS of IMS online. Each message must be predefined with its definition stored in a PDS library, commonly called Format Lib. The

IMS DC PROGRAMMING

01/08/2004

Page 7/ 115

definition is composed of several parts, each defining device input and output as well as message input and output formats. (This will be discussed in detail in the section on the Message Format Service.)

IMS Logging and Automatic Back Out

Logging and back outs are two important features of IMS. The logging feature records all database changes made and all messages sent during the execution of a batch or online program. There are two major differences between IMS batch and online logging. First, the log file (where the changes are recorded), is optional in the batch environment, but required in the online environment. Second, in online logging, two log files are used to record the data base activity -- the primary and the secondary. Both contain identical information for safety. If recording on the primary file becomes impossible (as with a data check on a tape drive). IMS automatically switches logging exclusively to the secondary log file and puts out a warning to the operator that this has occurred. This will give the operator time to correctly shut down IMS online so that new primary and secondary files can be used upon restart. If an online application program abends during execution, IMS will automatically back out (undo) changes made to all databases and message queues during the execution of the program. It will put them to the last program commit point. (In the batch class, you learned about the checkpoint facility available to an IMS program, which is one way to force a commit point. We will discuss another way to force a commit point in an MPP later in this course.) The back out of changes to the IMS resources is performed using the contents of the log file. This feature ensures the integrity of all the resources used by the abending program. Be aware that in your system design, IMS will discard the input message being processed when the program abends. When restarted, the MPP is given the next message waiting to be processed. So thought should be given to providing a way of automatically recreating and submitting the message in for processing if program abends. The following critical system information is recorded on the log data set:1. 2. 3. 4. 5. 6. 7. The receipt of an input message in the input queue The start of an MPP/BMP The receipt of a message by the MPP for processing Before and after images of database updates by the MPP/BMP The insert of a message into the queue by the MPP The termination of an MPP/BMP The successful receipt of an output message by the terminal

In addition to the above logging, all previous database record unchanged data is written to a dynamic log. This log information is only used for dynamic back out of a failing

IMS DC PROGRAMMING

01/08/2004

Page 8/ 115

MPP/BMP. As soon as the MPP/BMP reaches a synchronization point, the dynamic log information of this program is discarded.

IMS Online Control Region

Typically, only one production control region is started to support the entire online community. There are three ways to start the IMS online control region: A Cold start starts IMS from the beginning. It is done when the nucleus of IMS changed, as a new version of IMS or when fixes have been applied to a current release. All IMS files are formatted in the startup, and nothing is recovered. Cold starts are rarely needed. Warm starts are used most often to start IMS. It restores the environment and system files to the point at which IMS was properly brought down. Emergency restarts are used after an uncontrolled shutdown such as a power failure. It restores IMS to the point of failure. Any data entered after the last successful commit point is lost.

Resource Availability
A list of IMS databases available to the online system is submitted to the control region. A table of databases, called the Dynamic Allocation Table, is provided upon IMS online control region start-up. The IPC and data base administrator (DBA) have the ability to update this table once the control region becomes available. The databases are allocated exclusively to the online IMS control region and in order to access and process the databases, a program must be of the type that executes under the IMS control region. The most common types are MPP and BMP. A list of transactions and programs available to the online system is also submitted to the control region and must be defined to IMS prior to processing. This is done at system generation time. Once the control region becomes available, the IPC and data base administrator can alter the state of transactions and programs as to their availability to IMS. The IMS control region starts online message regions that schedule transactions for execution. The number of message regions started depends on the client's requirements. Depending on the releases of MVS and IMS/VS, as many as 255 dependent regions can be started at once. Basically, two types of message regions are started: Message Processing Regions and Batch Message Processing Regions.

Message Processing Regions

The IMS message-processing region (or message region) processes online transactions that have been queued from clients or the master terminal. The message region polls the

IMS DC PROGRAMMING

01/08/2004

Page 9/ 115

message queues searching for a transaction to process. The criteria for the search includes the transaction class, the transaction position in the queue, and the transaction classes defined for the region. Once a transaction is selected for processing, the region is no longer available to process any other transaction until the current transaction terminates.

Batch Message Processing Regions

IMS batch message processing regions process batch programs defined to have access to the control region and their allocated databases. Typically, only one or two of these regions are started, depending on the amount of batch processing required.

IMS DC PROGRAMMING

01/08/2004

Page 10/ 115

System Definitions
APPLCTN Macro

back

A APPLCTN macro is coded to define an application , its resources in terms of a PSB name and the application type. APPLCTN PSB=DFSIVP2,PGMTYPE=(TP,1) This specifies the PSB and the program name to be DFSIVP2 and it also specifies that the application is a MPP with a class of 1. The class may be omitted and specified in the TRANSACT macro(s). Other options possible are FPATH=YES | NO GPSB=name generates a PCB with an I/O PCB and an alternate PCB dynamically PGMTYPE=BATCH for BMP programs LANG=ASSEM or COBOL or PL/I and is relevant only if GPSB is specified SCHDTYP=PARALLEL | SERIAL. SERIAL is the default and the application can run in only one region

TRANSACT Macro
One or more TRANSACT macros follow an APPLCTN macro and associate a Transaction code (8 characters) with the application. More than one transaction can map to a single application. However one transaction cannot map to more than one application. The parameters on the transaction definition that will affect the scheduling options are: PROCLIM PARLIM MAXRGN PRTY The PARLIM parameter on the TRANSACT macro will determine when a transaction will be scheduled in another region. When the number of messages on the queue for this transaction exceeds the value on the PARLIM, another region will be used. A value of 0 schedules a new region every time a message comes. The MAXRGN parameter is used to restrict the number of MPRS that can process a transaction at any one time. A value of 0 sets no limit. PROCLIM(count,seconds) sets the max iterations as well as the max time that an application can run.

IMS DC PROGRAMMING

01/08/2004

Page 11/ 115

PRTY(normal,limit,limit count). Default is 1,1,65535 SPA=size for a conversational transaction. If coded IMS treats the transaction as a conversational transaction. The transactions are assigned to classes. The maximum number of transactions classes is set at system generation time by the MAXCLAS parameter of the IMSCTRL macro. Each dependent MPR can run up to four transaction classes. The order in which they are specified is a priority sequence. That means that the transaction class named first is the highest and the one named last is the lowest. Each MPR can have a different sequence of the same or different transaction combinations. The classes are named on the PROC statement of the JCL running the MPR. // PROC SOUT=A,RGN=56K,SYS2=, // CL1=001,CL2=000,CL3=000,CL4=000, // IMSID=,. . . . //* //REGION EXEC PGM=DFSRRC00,REGION=&RGN, // TIME=1440,DPRTY=(12,0), // PARM=(MSG,&CL1&CL2&CL3&CL4,. . .) The classes assigned to a dependent region can be changed through the /ASSIGN command. The /DIS ACTIVE command displays the dependent regions and status. The following conditions must be met for a successful scheduling: 1. An MPR region must be available. The termination of a prior transaction running in an MPR region triggers the scheduling process. 2. There must be a transaction input message in the queue. 3. The transaction and its program are not in a stopped state. 4. Enough buffer pool storage is available to load the program specification block (PSB) and the referenced database control blocks if not already in main storage. 5. The database processing intent does not conflict with an already active application program (a BMP for instance). The database intent of a program as scheduling time is determined via the PROCOPT= parameters in the PSB. Any conflicting situation during scheduling will only occur if a

IMS DC PROGRAMMING

01/08/2004

Page 12/ 115

segment type is declared exclusive use (PROCOPT=E) by the program being scheduled and an already active program references the segment in its PSB (any PROCOPT), or vice versa.

DATABASE
Each database needs to be defined by a DATABASE macro. The level of access is specified as well as the DBD name. The access levels are EX for exclusive, RD which allows only read access to the data base, RO that allows uncommitted reads to the database with PCBS that have a PROCOPT of GO, and UP for update intent. IMS normally uses an enqueue on the data base record while an application is processing the record. There are two situations where the enqueue / dequeue routines of program isolation are not used in processing a database call: If PROCOPT=GO (read only) is specified for the referenced segment (s) of the call. If PROCOPT=E (exclusive) is specified for the referenced segment (s) in the call. Note that possible conflicts with exclusive extent are resolved during scheduling time and, as such, cannot occur at call time. With the GO option, a program can retrieve data which has been altered or modified by another program still active in another region, and database changes made by that program are subject to being backed out. Exclusive intent may be required for long-running BMP programs that do not issue checkpoint calls. Otherwise, an excessively large enqueue/dequeue table in main storage may result.

IMS DC PROGRAMMING

01/08/2004

Page 13/ 115

Application Program Structure

START

back

INITIALIZE WORKING STORAGE

GU CALL ON I/O PCB FOR INPUT MESSAGE OTHER STATUS CODE ERROR GOBACK QC

INPUT VALIDATION

PROCESS DATABASE

ISRT OUTPUT MESSAGE USING I/O PCB

The principal DL/I message call function codes are: The GU, or get unique call. This call must be used to retrieve the first, or only, segment of the input message. The GN, or get next call. This call must be used to retrieve second and subsequent message segments.

IMS DC PROGRAMMING

01/08/2004

Page 14/ 115

The ISRT, or insert call. This call must be used to insert an output message segment into the output message queue. Note: these output message (s) will not be sent until the MPP terminates or requests another input message via a get unique. The CHNG or change destination call. This call can be used to set the output destination for subsequent insert calls IMS distinguishes the following types of transactions. Non-response transactions. Response transactions. Conversational transactions.

These IMS transaction characteristics are defined for each transaction during IMS system definition. With non-response transactions, IMS accepts multiple input messages (each being a transaction) from a terminal without a need for the terminal to first accept the corresponding output message, if any. With response transactions, IMS will not accept further transaction input from the terminal before the corresponding output message is sent and interpreted by the user. For conversational transactions, which are always response transactions IMS provides a unique scratch pad area (SPA) for each user to store information across successive input messages.

IMS DC PROGRAMMING

01/08/2004

Page 15/ 115

Introduction to Message Format Service

back

This section covers the following information on formatting messages via the use of an IBM product called Message Format Service (MFS). MFS Messages MFS Control Blocks Device Input Format (DIF) Message Input Descriptor (MID) Message Output Descriptor (MOD) Device Output Format (DOF) MFS Formats Device Statements Message statements Logical Pages

Defining MFS Messages

The MFS facility of IMS controls formatting of IMS online messages. When a message is sent to a display device such as a 3278 or 3178 terminal, certain keys perform special functions and need not be defined within the MFS format. These keys are as follows: PA1 - Used for logical paging (described later in this section). PA2 - Used to retrieve the next message waiting for the device. ENTER - Sends the message to the IMS Control Region to be processed.

MFS was designed so that an application program could send messages to devices and be device-independent. This independence allows messages to be sent to different devices without changing the application program code. Only the message format need be regenerated for the new device. MFS works with a set of control blocks that define how the message will be formatted to the client and the application program. The blocks also define how sending and receiving devices will format the message. Four control blocks are involved in creating a message with MFS: Device Input Format (DIF) Message Input Descriptor (MID)

IMS DC PROGRAMMING

01/08/2004

Page 16/ 115

Message Output Descriptor (MOD) Device Output Format (DOF)

The flow of an MFS message between a client and an online program is shown in Figure below.

MFS SUPPORTED DEVICE

DOF

MOD

IMS

MFS
IMS DIF MID ONLINE PROGRAM

(MFS

(MFS CONTROL BLOCKS) Flow of Message using MFS The processing of a message starts with a client entering data on an MFS- supported device. When the ENTER key or a PF key, is pressed, a message is transmitted to IMS. IMS analyzes the message to see if the following applies: It is an IMS operator command that it has to respond to.

IMS DC PROGRAMMING

01/08/2004

Page 17/ 115

It is message to be sent to another device. An application program needs to be scheduled.

The message needs to be passed to MFS for further formatting. If the message is to be passed to MFS, it is formatted based on the associated DIF. MFS reformats the message, removing all device-dependent data, according to the MID definition. The message is sent to the application program for processing. Once the message is processed, the program edits and sends a response back to the originating client. Again, IMS edits the message, and passes it back to MFS if MFS is required. MFS interprets the data sent from the application program using the MOD control block. It then creates the screen to be sent to the client by combining the interpreted data with the DOF control block.

MFS Control Blocks

To get a better understanding of MFS and how it functions, we will explore the relationships between the four MFS control blocks. The application programmer normally does the actual definition of the MFS control blocks. The Combination of MID/MOD and DIF/DOF control blocks for a given message make up the format.

Device input Format

Every device sending a message using MFS must first be defined through the DIF control block. The DIF describes the physical device characteristics and how messages are formatted from the device. Typically, each format will create its own DIF, although a single DIF can be used by many other formats. Each time a device sends a message MFS retrieves the appropriate DIF to determine the format of the message, before restructuring it and sending it to the application program. MFS generates the DIF based on the device information supplied in the format.

Message Input Descriptor

Once MFS receives a message from a device, it restructures the message according to the format defined in the MID. Once the message is reformatted, the message is then sent to the application program for processing. Note: For every MID, there must be a corresponding DIF, and vice versa.

IMS DC PROGRAMMING

01/08/2004

Page 18/ 115

Message Output Descriptor

When an online IMS application program wishes to send a message back to an operator, the message must be constructed according to the MOD definition. It is not mandatory for every MOD to have a corresponding MID. If no MID exists for a MOD, MFS will not process any data input to the MOD.

Device Output Format

After MFS receives a message formatted by the MOD, it reformats the message for the receiving device using the DOF. The DOF describes how message are formatted to the device. Like the DIF, a single DOF can be used by many formats. Each time a device receives a message, MFS retrieves the appropriate DOF to determine the format of the message before restructuring it and sending it to the device, MFS generates the DOF based on the device information supplied in the format. For every DOF, there must be a corresponding MOD. In many cases, the input and output screens appear the same. In this case, we can use a feature of MFS coding that allows one set of source statements to generate both the DIF and DOF control blocks. This is called coding a DIF/DOF. Note: For every MOD, there must be a corresponding DOF.

MFS Sample
1. Type in response: /FOR CT70000M 2. Press the ENTER key. You should get the following screen display. See the MFS format statements that follow to understand why. *************************** * THIS IS A TEST FORMAT * * FOR THE IMS ONLINE * * COURSE. * * * * PRESS PF1 FOR EXAMPLE * * OF ATTRIBUTES * * * * PRESS PF3 TO EXIT * * FROM IMS * ***************************

IMS DC PROGRAMMING

01/08/2004

Page 19/ 115

From here, press PF1 for the following screen display: ************************************** * THIS IS AN EXAMPLE OF THE VARIOUS * * ATTRIBUTES AVAILABLE TO A FORMAT. * ************************************** ALPHABETIC,NONPROTECTED,NORMAL INTENS:ALPHABETIC,PROTECTED ,NORMAL INTENS: ALPHABETIC,NONPROTECTED,HIGH INTENS: ALPHABETIC,PROTECTED ,HIGH INTENS: ALPHABETIC,NONPROTECTED,NONDISPLAY : ALPHABETIC,PROTECTED ,NONDISPLAY : NUMERIC ,NONPROTECTED,NORMAL INTENS: NUMERIC ,PROTECTED ,NORMAL INTENS: NUMERIC ,NONPROTECTED,HIGH INTENS: NUMERIC ,PROTECTED ,HIGH INTENS: NUMERIC ,NONPROTECTED,NONDISPLAY : NUMERIC ,PROTECTED ,NONDISPLAY : PRESS PF1 TO RETURN TO PREVIOUS FORMAT Above are some of the attributes available. At this point, you can enter data into the various fields to see how they react to the listed specifications. When you finish testing, press PF1 to return to the first format, then press PF3 to exit IMS.

Creating an MFS Format

The MFS language used to create formats is a set of IMS/VS Assembler Language macro statements. This section describes some common statements and their relationships in defining the MFS control blocks. When defining an MFS format, remember that the statements are designed around the four MFS control blocksthe DIF, DOF, MID, and MOD. Within each statement set there is a logical hierarchy of statements that must be followed. The hierarchy will be shown before each set of control block sources is explained. There is no strict order of coding MFS control blocks, however, most application programmers code the control blocks in a physical then logical sequence (first code the DIF/DOF, then the MID/MOD). The statements discussed in this section will be presented in the order you would typically code when constructing a format definition. To better understand this process, we will construct an actual format as each statement is discussed. The device statements have a hierarchy as follows: FMT--------------Defines a device format (DIF/DOF)

IMS DC PROGRAMMING

01/08/2004

Page 20/ 115

DEV------------Defines device characteristics DIV----------Defines device formats within DIF and DOF DPAGE------Defines logical page, cursor position, and also a fill character DFLD----Defines input, output, and literal fields that will appear on the device DFLD . DEV------------Defines another device characteristics. One Format set can cater for multiple device Types, IMS making the choice of which set to Use depending on terminal type. DIV DPAGE DFLD DFLD . FMTEND-----------Defines the end of the DIF or DOF Note: All statements figures will follow the same notation. The parameters within braces {} and separated by the word or, indicate you should choose one. The parameters within <> indicate they are optional. Lower case letters and words indicate the value is determined by you, Capital letters, numbers, and special characters =,( ) indicate they should be coded exactly as seen. If continuing parameters from one line to the next, you need a nonblank character in column 72 and the statement will continue 16. An asterisk (*) in column 1 of your MFS source indicates to the assembler that this is a comment statement. Some parameters may be optional but may not be indicated within <>.

FMT- Format Definition

The FMT statement defines the beginning of a device format definition (DIF/DOF). The statements following the FMT further define how date is to be formatted on the device. Figure 2 shows the coding format for the FMT statement.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------label FMT <blanks or comments>

Figure 2 FMT Statement Label: This is the label associated with the device format. It can be from one to six characters in length, and will be referenced by the SOR=parameter on the MSG statement coded later. This label will be used to identify the DIF and DOF control blocks.

IMS DC PROGRAMMING

01/08/2004

Page 21/ 115

To begin coding example, start with a FMT statement as shown below.

-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 ----------------------------------------------------------------------ABCSTA FMT

DEV- Device Characteristics

After the FMT statement, code the DEV statement, which defines the characteristics of the device that we are communicating with. Figure 3 shows the coding format for the DEV statement.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 ----------------------------------------------------------------------------- the parameters below are for 3270 displays ------DEV TYPE={(3270,n) OR 3270-An), X FEAT=IGNORE, X PFK=(dfldname,{literal,. . .or X nn=literal,. . .}), X DSCA=Xnnnn, X SYSMSG=msgfield X ------- the parameters below are for printers ------DEV TYPE={(3270P,1) or (3270P , 2) or SCS 1), FEAT=IGNORE, WIDTH=nnn, PAGE=nn

X X X

Figure 3. DEV Statement

TYPE This parameter specifies the type and model of the device being used.. FEAT This parameter specifies the feature to be used for the device. Use IGNORE to specify that device feature will be ignored, If IGNORE is not specified, FEAT= must specify exactly what was specified on the TERMINAL macro during the IMS/VS system definition. When TYPE=3270P (printer) and FEAT=IGNORE, MFS will allow a line width of 120 bytes. PFK

IMS DC PROGRAMMING

01/08/2004

Page 22/ 115

The PFK parameter defines the input field and literal values for the PF keys. The first sub parameter dfldname is normally referenced by a message field (MFLD) statement (discussed in the MSG section) and cannot be used as the label of a DFLD statement within this DEV definition. The second and subsequent sub parameter(s) in positional or keyword format specify the value that will be generated when a PF key is pressed. When used positionally, MFS will assume a one-to-one correspondence between the literal and the PF key. If a PF key is not assigned, a comma must be used to hold the position of the unassigned PF key. In the nn=literal form, MFS associates the literal with the PF key specified by nn. There is no need for any place holding in this manner. The maximum number of PF keys is currently 36. If the literals are different lengths at the time the formats are being created, MFS will pad each literal on the right with blanks so that each will be as long as the longest literal. The PFK parameter can also be set to the following to support Physical paging. NEXTPP or NEXTMSGP or NEXTLP or ENDMPPI NEXTPP fetches the next physical page of a message. NEXTMSGP skips the remaining pages of the physical message and skips to the next physical message. NEXTLP requests the next logical page of a message. ENDMPPI indicates the end of entry of data for a input message with multiple pages. Remember, a period following an operator command will cause all data after the period to be treated as comments. Be sure to add a period after the operator command so that the other data contained as part of the message will be treated as a comment. WIDTH The WIDTH parameter is for printers and specifies the line width for input or output. The maximum width is 255. The default values are 132 for SCSI, and 120 for 3270p output. PAGE The PAGE parameter, also for printers, defines the number of print lines to a page The range is from 1 to 255, with the default value being 55. DSCA parameter. When X00A0 causes unprotected field in the terminal to be erased before new data is written to the terminal. X00C0 causes the entire terminal buffer to be cleared before data is written to the terminal. SYSMSG indicates the name of a DFLD that can be used to display messages from IMS. The field must be 79 characters long. Programs can write to this field too. MFS uses the TYPE and FEAT parameters to create the control block name. First byte is set to X00 for 3270-1, X02 for 3270-2 and so on. The second byte is set to X7F if the features of the device are ignored. Next 6 bytes are from the FMT macro label. 1st

IMS DC PROGRAMMING

01/08/2004

Page 23/ 115

character of the label in the block name is lowercase for a DIF block and upper case for a DOF block, where the same statements generate both a DOF as well as a DIF. Let's proceed with our coding example and include the DEV statement. Remember from the screen layout that PF2 will cause an application program with transaction code ABCPSTPT to be scheduled, and that PF3 will take the client to the maintenance menu with mod name ABCOMENU.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------ABCSTA FMT DEV TYPE=3270-A2,FEAT=IGNORE,PFK=(PFKEYS00, 2='ABCPSTPT , 3='/FOR ABCOMENU.)

X X

DIV-Device Format
The next device statement is DIV, which defines the device formats within the DIF and DOF. Although there are many parameters, we will discuss only one, as shown in Figure 4,
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------DIV TYPE={INPUT or OUTPUT or INOUT}

Figure 4. DIV Statement TYPE The TYPE parameter identifies whether this is DIF, DOF, of both. Typically, the same input and output formats are used. In that case, the value INOUT is used for TYPE. It is not necessary to code separate DIF and DOF source statements when using TYPE=INOUT. With INOUT, the MFS utilities will generate the DIF and DOF control blocks and differentiate the two. It does this by tweaking the first character of the label on the FMT macro to upper case for a DOF and lower case for the DIF. Always code INOUT for an 3270 display station Adding the DIV statement to our code, we now have the following:
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 ------------------------------------------------------------------------

IMS DC PROGRAMMING ABCSTA FMT DEV DIV

01/08/2004

Page 24/ 115

TYPE=3270-A2,FEAT=IGNORE,PFK=(PFKEYS00, 2=ABCPSTPT 3=/FOR ABCOMENU.) TYPE=INOUT

X X

DPAGE Device Logical Page

The DPAGE statement is normally not coded, unless you are using logical paging, or you wish to take advantage of a device option such as initial cursor positioning. Another use of the DPAGE is to specify a fill character for output device fields. Figure 5 shows the format of the statement, as we will use in this course.

-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------DPAGE CURSOR=((LL,cc[,cfield])), X <FILL={PT or Xhh OR Cc OR NONE OR NULL}>, X <MULT=YES>

Figure 5. DPAGE Statement CURSOR The CURSOR parameter allows you to specify where the cursor is initially placed on the display, using the coordinates line (11) and column (cc). The values for 11 and cc depend on the device type, such as a 24 x 80 or 32 x 80 display. If the DPAGE statement is left off of the format, the default is for the cursor to be initially placed at position (1,2) on the display. Specify cfield that points to a pseudo field (a MFLD without a corresponding DFLD) that defines a field of 4 bytes. The first two bytes will have the LL value and the next two bytes a CC value which is the position of the cursor when the enter key was pressed. FILL The FILL parameter allows you to specify a fill character or fill action to be taken. The default for a 3270 display device is FILL=PT. The default for all other devices is FILL=X40. FILL=PT will cause a tab character to be placed at the end of the data placed into a DFLD if the data from the MOD did not fill the field. This tab character will cause the remaining data to be cleared from the field on output, when the data supplied by the program is less than the length of the field FILL=Xhh will cause the character representation of the hex value to be used as fill in each of the output device fields.

IMS DC PROGRAMMING

01/08/2004

Page 25/ 115

FILL=Cc will cause the character specified to be used as fill in each of the output device fields. FILL=NONE. This value is specified when the FILL= parameter is used on the MOD. If this is not used, the FILL= on the MOD will be ignored. FILL=NULL means that the output device fields are not to be filled. MULT=YES specifies that multiple physical pages can be used to generate an input message. Let's add the DPAGE statement and see how our format looks.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------ABCSTA FMT DEV TYPE=3270-A2,FEAT=IGNORE,PFK=(PFKEYS00, X 2=ABCPSTPT X 3=/FOR ABCOMENU.) DIV TYPE=INOUT DPAGE CURSOR=((06,38)),FILL=PT

DFLD - Device Field

Now that we have defined the device formats and characteristics, we need to define the input, output, literals, and fields that will appear on the device. This is done via the DFLD statement. Figure 6 shows some of the common parameters used.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------....... the parameters below are for 3270 displays ....... label DFLD <literal'>, X POS=(11,cc), X LTH=nn, X ATTR=({ALPHA or NUM},{NOPROT or PROT} X (NOMOD or MOD },{NORM or NONDISP or HI}), X <EATTR=(HD|HBLINK|HREV|HUL, BLUE|RED|PINK|GREEN|TURQ|YELLOW|NEUTRAL)> ....... the parameters below are for printers ....... label DELD <literal'> POS=(11,cc), LTH=nn, ATTR=(NO or YES)

X X X

IMS DC PROGRAMMING

01/08/2004

Page 26/ 115

Figure 6. DFLD Statement label This parameter is the label associated with the DFLD. It can be from one to eight characters in length, and typically has a naming convention. It can be descriptive of the position of the field on the screen (such as DLFD1135 the field on line 11, column 35), or it can be descriptive of the purpose of the field (DATEIN Status Date In field). If no literal is specified, you must provide a label for the DFLD, which is normally referenced by an MFLD statement (discussed in the MSG section). literal This parameter is optional. It is only required when you want a literal to appear on the display. The length of the literal depends on the device and does not need to be specified. For a 3270 display and 3270P printer, a maximum of 256 bytes is allowed. Labels cannot be used on DFLDS that specify literals. POS This parameter specifies the display coordinates for the field in a LL,CC format. The values for line (LL) and column (cc) depend on the device defined. POS=(01,01) is reserved and cannot be defined by a DLFD. LTH The LTH parameter specifies the length of the field. The maximum value depends on the device, but must not exceed the physical page size of the device. If a literal is specified, there is no need to code the LTH parameter since the actual literal length will be used. The Maximum length is the maximum page size for the device type, minus one. Note: POS and LTH do not account for the 1 byte on the 3270 display device used for holding the attribute information. It is necessary to account for this byte while in the design of the display screen. If the field starts in column 1 of a line, (with the exception of line 1), the attribute byte will occupy the last byte on the preceding line. ATTR This keyword allows the programmer to define how the field will physically appear on the screen. The common attribute sub parameters are described below. EATTR This attribute is used to define the color of the field, if the terminal supports color. ALPHA / NUM This is used to specify if the Numeric Lock feature of a keyboard will be used. This means that normally only numeric data may be entered into this field. For a non literal field, the default is ALPHA. Be very careful not to rely on the NUM sub parameter for

IMS DC PROGRAMMING

01/08/2004

Page 27/ 115

editing, as most new keyboards will allow the user to disable the Numeric Lock feature and/or type upper case alphabetic data into a numeric field. Note: The default for a literal field is NUM. NOPROT / PROT This sub parameter specifies whether the field is protected from input by the client (PROT), or the client may input data into the field (NOPROT). Note: If PROT is used in combination with NUM, an auto-skip feature is enabled. That is, when the last byte of a NOPROT field is filled, the cursor will automatically skip to the first byte of the next NOPROT field on the screen. The default for a literal field is PROT. For a non-literal field, the default is NOPROT. NOMOD / MOD These sub parameters cause the Modified Data Tag (MDT) to be set MOD or NOMOD. The MDT tells MFS whether the field has been modified by the client. IF MOD is specified, the MDT will be yes whether or not it was actually modified. The current data on the display will be included in the message, instead of only those fields that were modified. Note: Normally, all DFLDS that will be used in the MID should have the MOD attribute specified. This will cause the inclusion of all MID fields when creating the message, whether or not the client actually modified those fields. The default is always NOMOD. NORM, NODISP This sub parameter specifies whether the field should be displayed in normal intensity (NORM), hidden from client view (NODISP), or highlighted bright HI intensity (H) . The default is always NORM. FMTEND The last device statement is the FMTEND. It denotes the end of a FMT, which means the end of a DIF or DOF, Figure 7 shows the FMTEND statement structure.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------FMTEND

Figure-7, FMTEND Statement Let's complete our example format by adding the DFLDS for the fields and literals we want displayed on the device.

IMS DC PROGRAMMING

01/08/2004

Page 28/ 115

-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------PRINT NOGEN 1 ABCSTA FMT DEV TYPE=32700A2,FEAT=IGNORE,PFK=(PFKEYSOO, X 2=ABCPSTPT X 3=/FOR ABCOMENU.) DIV TYPE=INOUT DPAGE CURSOR=((06,38)),FILL=PT DFLD ABCPSTAT,POS=(01,2),ATTR=(NUM,PROT,HI) 2 DFLD ABC RENTAL COMPANY,POS=(01,26), X ATTR=(ALPHA,PROT,HI) DFLD ABCOSTAT,POS=(01,56),ATTR=(ALPHA,PROT,HI) 3 DFLD DATE:,POS=(02,2),ATTR=(ALPHA,PROT,HI) SYSDATE DFLD POS=(02,8),LTH=8,ATTR=(ALPHA,PROT,NORM) 4 DFLD STATUS DISPLAY,POS=(02,28),ATTR=(ALPHA,PROT,HI) DFLD TIME:,POS=(02,56),ATTR=(ALPHA,PROT,HI) SYSTIME DFLD POS=(02,62),LTH=08,ATTR=(ALPHA,PROT,NORM) 4 DFLD ITEM NUMBER:,POS=(06,25),ATTR=(ALPHA,PROT,HI) ITEMNUM DFLD POS=(06,38),LTH=06,ATTR=(NUM,NOPROT,NORM,MOD) 5 DFLD (PF2 - PRINT STATUS HISTORY),POS=(08,24), X ATTR=(NNM,PROT,HI) DFLD (PF3 - RETURN TO MENU),POS=(09,24), X ATTR=(ALPHA,PORT,HI) DFLD ========================================================X ===========,POS=(10,2),ATTR=(ALPHA,PROT,HI) DFLD STATUS CODE:,POS=(11,02),ATTR=(ALPHA,PROT,HI) STCODE DFLD POS=(11,15),LTH=01,ATTR=(ALPHA,PORT,NORM) DFLD STATUS DATE IN:,POS=(11,19),ATTR=(ALPHA,PROT,HI) STDTIN DFLD POS=(11,35),LTH=06,ATTR=(ALPHA,PROT,NORM) DFLD STATUS DATE OUT,POS=(11,44),ATTR=(ALPHA,PROT,HI) STDTOUT DFLD POS=(11,61),LTH=06,ATTR=(ALPHA,PROT,NORM) DFLD STATUS DESCRIPTION: ,POS=(13,02), X ATTR=(ALPHA,PROT,HI) STDESC DFLD POS=(13,22),LTH=20,ATTR=(ALPHA,PROT,NORM) FMTEND

This completes the physical portion of the screen. Before beginning the logical portion (MID/MOD), take a look at the numbered points of interest indicated in the above example: 1. The PRINT NOGEN is added so that the message and device macro statement expansion will not be printed in the output listing. 2. This is the literal for the transaction name. 3. This is the literal for the format MOD name. 4. This is where the date and time system variables will be displayed.

IMS DC PROGRAMMING

01/08/2004

Page 29/ 115

5. This is the only field the client can enter data. This is indicated by the NOPROT attribute. It is recommended that you include the following information on every format you create: Format MOD name

Message Statements
The message statements define the MID and MOD control blocks and hierarchically consist of the following statements: MSG-----------Defines either a MID or MOD LPAGE--------omitted if logical paging is not required PASSWORD----Defines password fields in following MFLD statements, optional MFLD-----A password field, program will not get This as it is processed by IMS and is Stripped off MFLD-----Another password field . SEG---------Defines first message segment MFLD-----Defines message data fields which will be contained in messages sent to and from IMS MFLD-----Another field . . SEG---------Defines 2nd message segment (optional) MFLD-----Defines message data for this segment MFLD-----Another field . . LPAGE--------omitted if logical paging is not required PASSWORD----Defines password fields in following MFLD statements, optional MFLD-----A password field, program will not get This as it is processed by IMS and is Stripped off MFLD-----Another password field . SEG---------Defines first message segment MFLD-----Defines message data fields which will be contained in messages sent to and from

IMS DC PROGRAMMING

01/08/2004

Page 30/ 115

IMS MFLD-----Another . . SEG---------Defines MFLD-----Defines MFLD-----Another . . MSGEND---------Defines

field 2nd message segment (optional) message data for this segment field the end of either a MID or MOD

MSG-Message Definition
The MSG statement defines either a MID or MOD. Figure 8 shows the various parameters associated with a MSG statement.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------label MSG <TYPE={INPUT or OUTPUT},> X SOR=(format name<,IGNORE>), X <OPT={1 or 2 or 3},> X <NXT=message statement name><,> X ..... the additional parameters below are valid for TYPE=OUTPUT only.. <PAGE={NO or Yes}>, X <FILL={C or Cc or NULL or PT}>

Figure 8. MSG Statement label This is required alphanumeric name that is used by the MFS utility to construct the control block (MID or MOD) member name in the format library. This may also be the message statement name referenced by the optional NXT=parameter of another message descriptor. The EDS User's Guide Volume 5 naming conventions for the label are the following: Character(s) 1-3 - Contains the account or system code. Character(s)4 - Depends on whether a MID or MOD. (Contains an I if this is a MID, an O if this is a MOD). Character(s) 5-8 - User or account assigned. Note: Be careful to keep the labels unique within an IMS system. The label is the only way that MFS knows which control block to use. TYPE

IMS DC PROGRAMMING

01/08/2004

Page 31/ 115

This parameter identifies whether the message is a MID or MOD. When coding a MID, specify TYPE=INPUT. For a MOD, specify TYPE=OUTPUT. It is an optional parameter when coding the MID because the default is TYPE=INPUT. SOR This parameter points to the device format statement, which defines the device and data fields that will be processed by the message descriptor. The format name is the label name associated with the FMT statement. (See Device Statements for more detail on the FMT statement.) If the IGNORE is specified for TYPE=OUTPUT, MFS will use fields for the device with FEAT=IGNORE. (See DEV-Device Characteristics for more detail on the FEAT=option.) Only specify IGNORE for TYPE=INPUT if the corresponding MOD specified IGNORE. Note: Since you will typically see FEAT=IGNORE on the device FMT statements, we will code IGNORE in this course. OPT This parameter specifies the MFS formatting option to be used for message editing. Since Option 1 offers a standard MFS formatting of messages, it is used in this course and workshops. The other options allow for data compression within the message, and are not commonly used because the use of options other than OPT=1 will increase the program complexity. OPT=1 is the default. Refer to the IMS/VS Message Format Service User's Guide, or IMS/VS Version Message Format Service User's Guide for details on the other MFS format options.) NXT This parameter indicates the next message descriptor to be used as a result of message processing. This means that a MID can point to a MOD, or a MOD to a MID, by specifying the message statement name (or MSG label name) for the NXT option. PAGE This parameter specifies whether (YES) or not (NO) operator logical paging (forward and backward) is to be used for the MOD. (See Logical Pages for more detail on logical paging. Refer to the IMS/VS Message Format Service User's Guide, or IMS/VS Message Format Service User's Guide for details on how to use this option for both logical and physical paging.) Note: Since this course does not teach logical paging, we will use PAGE=NO in all workshops. (The default for this parameter is PAGE=NO, so it is not required in TYPE=OUTPUT source.) FILL This parameter specifies the fill character to be used for output fields. FILL=C'c' will cause the character specified to be used as fill in each of the output device fields. FILL=C' 'is the default.

IMS DC PROGRAMMING

01/08/2004

Page 32/ 115

FILL=NULL means that the output device fields are not to be filled. FILL=PT. After placing the data from the MOD into the output device field, if it does not fill the device output field, a tab character will be placed at the end of the data, which causes the rest of the device output field to be cleared. Remember, if the FILL= is used on the MOD, the DPAGE must specify FILL=NONE. Since we coded FILL=PT on the DPAGE, we do not need to code a FILL parameter here. For our example format we will code the MID first, followed by the MOD. This is done since the MID defines the input message sent into IMS, then the MOD defines the output message sent from IMS.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------ABCISTAT MSG TYPE=INPUT,SOR=(ABCSTA,IGNORE),OPT=1,NXT=ABCOSTAT

SEG - Message Segment

The SEG statement defines message segments (pieces of the same message, not to be confused with data base segments). It is an optional statement and is needed only for multisegmented messages. In this course, we will address only single segment messages because that is what you will encounter most on your account. Although the SEG statement is optional, if you do not code one, MFS will generate one at assembly time and give a return code of RC 0004. This course recommends coding the SEG statement for the sake of readability, consistency, and debugging ease. In addition, the Performance Factor section of the MFS Guide recommends that the number of segments in a message be minimized. Figure 9 describes the coding of a SEG statement.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------label SEG

Figure-9, SEG Statement label This is an optional alphanumeric name that can be used to identify multiple segments in a message. When only one SEG statement is coded, a label is typically omitted. SEG

IMS DC PROGRAMMING

01/08/2004

Page 33/ 115

This defines the beginning of a message segment. Only single segment messages are used for this course. Our example format now looks like the following with the SEG statement added.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------ABCISTAT MSG TYPE=INPUT,SOR=(ABCSTA,IGNORE),OPT=1,NXT=ABCOSTAT SEG

MFLD - Message Field

The MFLD statement defines how the data fields will be transmitted to and from the application program. Every MSG statement must have at least one MFLD statement. Note: Typically, each MFLD maps to a field on the device. (Remember the DFLD's and their labels.) However, it is not a requirement that every MFLD maps to a DFLD. If your MFLD references a DFLD label, that label must exist or a return code of RC 0004 will be returned. Figure 10 shows the MFLD statement structure.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -------------------------------------------------------------------------- the parameters below are for Type-INPUT only ..... label MFLD {(dfldname,literal) or dfldname or literal) X LTH=nn, X JUST={L or R}, X ATTR={NO or YES}, X FILL={X40 OR Xnn or Cc or NULL} .....the parameters below are for TYPE=OUTPUT only .... <label> MFLD {(dfldname,literal) or dfldname or (dfldname,system-literal)}, LTH=nn, JUST={L or R), ATTR={NO or YES} X X X X X

Figure-10. MFLD Statement label This is an optional label that can be used to help document the field in the message descriptor. It can be from one to eight alphanumeric characters long.

IMS DC PROGRAMMING

01/08/2004

Page 34/ 115

dfldname This is the device field name that this message field maps to. The device field name is the label attached to the DFLD statement (described earlier). If using a DFLD, think of it as either the source of the data for this MFLD (in the case of a MID), or the screen destination for the data contained in the MFLD (in the case of a MOD). You will have an MFLD for every field you wish to have contained in the message to and from your application program, as well as any system literals (in the MOD only) you want displayed on the screen. If you use dfldname, literal' for an MFLD in the MID, and the dfldname does not contain any data, the literal is placed into the MFLD. If you use (dfldname, literal')) for an MFLD in the MOD, the literal is placed in dfldname referenced. Do not allocate space in the MOD from program when using this form. literal This is a literal value to be inserted in the message. This is used mainly to have the transaction code inserted as part of a message to send default data to a program. The literal length cannot exceed 256. System literal You can include system literals only for output messages. These literals are generated prior to the device receiving the message. You cannot specify ATTR, LTH, or JUST with system literals. System literals include the following: DATE1 - 6 bytes - YY.DDD format DATE2 - 8 bytes - MM/DD/YY format DATE3 - 8 bytes - DD/MM/DD format DATE4 - 8 bytes - YY/MM/DD format TIME - 8 bytes HH:MM:SS format

LTH This parameter specifies the length of the message field. The range is from 1 to 8000 bytes. The length is optional, if a literal specified. If LTH is specified for a literal, the field will either be padded or truncated. If omitted for a literal, MFS determines the length. JUST This specifies if the data is to be right (R) or left (L) justified within the message field. This also implies truncation right or left. A right-justified field is truncated on the left. A left-justified field is truncated on the right. The default setting is left-justification. ATTR This parameter determines if the 3270 attributes can be modified by the application program. If YES is specified, you must include an extra two bytes in the LTH parameter

IMS DC PROGRAMMING

01/08/2004

Page 35/ 115

for the field. These represent the attribute bytes. The I/O area in your application program for the MID and / or MOD must account for not only the actual length of the field, but also the extra two attribute bytes preceding each field. If NO is specified, the LTH parameter specifies the actual length of the field, and no attribute bytes need to be considered in the application program I/O area for the MID/or MOD. When NO is specified, the application program cannot change the attributes of the field displayed on the device. If ATTR=YES is specified for an MFLD on a MID, MFS will fill the two attribute bytes with blanks prior to putting the message into the message queue. Note: This course recommends only using ATTR=YES for MFLDS in the MOD. FILL The FILL parameter is for input message fields only. It is used to specify a fill character for padding when the data from the device (DFLD) is less than the length specified for the MFLD. X nn means that the character representative of the hex field will be used to pad the input MFLD. The default fill value is X'40'. C'c' means that the character specified will be used to pad the input MFLD. NULL means the field will be compressed to the left by the amount of the missing data. If there is no data present, the field is compressed completely. Note that this can cause positions of fields in the input message to shift!. MSGEND Message End The last message statement is the MSGEND, and denotes the end of a MSG, which means the end of a MID or MOD. Figure-11 shows the MSGEND statement structure.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------MSGEND

Figure-11. MSGEND Statement Let's continue to code our example format. First we must determine what fields we need in the application program. These will be the MFLDS that make up the MID. We need to discuss what would happen to our message when the ENTER key or a PF is pressed.

IMS DC PROGRAMMING

01/08/2004

Page 36/ 115

When we talked about how messages are sent to and from application programs, it was stated that IMS looks at the beginning of each message (MID) to determine what to do. These are the three types of messages that can be sent from a terminal: If the first byte is a slash (/), IMS interprets the message as an IMS operator command. If the first eight or less bytes followed by a space reference a logical terminal (LTERM), the message following is directed to that device. A logical terminal is also referred to as a logical device, as it does not actually have to be a terminal. If the first eight or less bytes, followed by a space reference a transaction code, the corresponding application program is scheduled for execution and the message is sent to the transaction queue for processing. In our example, the client wanted PF2 to cause a transaction to be started (ABCPSTPT), PF3 to return to a menu, modname ABCOMENU, and the ENTER key to schedule our transaction (ABCPSTAT). Depending on whether a PF is pressed or not, we must ensure that we have a valid message created. Remember, the MID will always be the sum of all MFLDS we have coded. Let's see how the fields will be defined for our MID.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------ABCISTAT MSG TYPE=INPUT,SOR=(ABCSTA,IGNORE),OPT=1,NXT=ABCOSTAT SEG MFLD (PFKEYSOO,'ABCPSTAT '),LTH=14,JUST=L,ATTR=NO 1 MFLD ITEMNUM,LTH=06,JUST=R,ATTR=NO,FILL=X'40' 2 MSGEND

That concludes defining our MID. 1. This input MFLD is used to define the first 14 bytes of the message. If a predefined PF is pressed, the literal assigned to the PF on the DEV statement of the FMT is placed in the first 14 bytes. The dfldname PFKEYSOO is the name assigned on the DEV statement. The length of the MFLD is determined by the longest PF literal. If a pre-defined PF is not pressed, the literal is assigned to the MFLD. 2. This MFLD shows how an input data field is coded for a MID. With ATTR=NO, you do not include the two attribute bytes as part of the length. FILL=X'40' will cause blanks to be placed in the field if the client does not type any data into the DFLD ITEMNUM prior to pressing the ENTER key. Let's continue to code our example format. We need to determine what fields will be sent by the application program. We may want to change the attributes of the fields (for instance, add high intensity). In addition, a couple of system literals will be supplied by

IMS DC PROGRAMMING

01/08/2004

Page 37/ 115

MFS. The system literals can be placed anywhere in the MOD but it is best of place them in the beginning of the end. Lets code the MOD and add the source to our MID.
-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------ABCISTAT MSG TYPE=INPUT,SOR=(ABCSTA,IGNORE),OPT=1,NXT=ABCOSTAT SEG MFLD (PFKEYSOO,'ABCPSTAT '),LTH=14,JUST=L,ATTR=NO MFLD ITEMNUM,LTH=06,JUST=R,ATTR=NNO,FILL=X'40' MSGEND ABCOSTAT MSG TYPE=OUTPUT,SOR=(ABCSTA,IGNORE),OPT=1,PAGE=NO, X NXT=ABCISTAT 1 SEG MFLD (SYSDATE,DATE2) 2 MFLD (SYSTIME,TIME) 2 MFLD ITEMNUM,LTH=08,JUST=R,ATTR=YES 3 MFLD STCODE,LTH=03,JUST=L,ATTR=YES MFLD STDTIN,LTH=08,JUST-L,ATTR=YES MFLD STDTOUT,LTH=08,JUST=L,ATTR=YES MFLD STDESC,LTH=22,JUST=L,ATTR=YES MSGEND END 4

The additional points of interest are also indicated by a string of periods followed by a number. These comments are not coded in the format. 1. This NXT=points logically to the MOD label, and the NXT=in the MOD points to the MID label. This will be discussed further in the IMS Online coding section. 2. These MFLDS define the system literal DATE2 (in MM/DD/YY format) and the system literal for TIME (format HH:MM:SS). The actual date and time are not part of the message data returned from the program. They are provided by MFS when the DOF and MOD are combined to create the final formatted screen for the client. 3. This MFLD represents how each data field is typically coded in a MOD. Notice that in the MOD, ATTR=YES is coded for output fields where the application program requires the ability to change attribute settings. As with the MID MFLD statements, when ATTR=YES, you must increase the logical length of the field by two bytes. 4. The END statement is for the Assembler Language to indicate the end for the source code. The completed MFS (including comments and proper documentation) is shown below. Be sure to follow any additional account standards when creating MFS source at your account.

IMS DC PROGRAMMING

01/08/2004

Page 38/ 115

IMS DC PROGRAMMING

01/08/2004

Page 39/ 115

-----------------------------------------------------------------------COLUMNS ****#****1*****1***2****$****3****$****4****$****5****$****6****$*****77 1 0 6 0 0 0 0 0 12 -----------------------------------------------------------------------PRINT NOGEN 1 ABCSTA FMT DEV TYPE=32700A2,FEAT=IGNORE,PFK=(PFKEYSOO, X 2=ABCPSTPT X 3=/FOR ABCOMENU.) DIV TYPE=INOUT DPAGE CURSOR=((06,38)),FILL=PT DFLD ABCPSTAT,POS=(01,2),ATTR=(NUM,PROT,HI) DFLD ABC RENTAL COMPANY,POS=(01,26), X ATTR=(ALPHA,PROT,HI) DFLD ABCOSTAT,POS=(01,56),ATTR=(ALPHA,PROT,HI) DFLD DATE:,POS=(02,2),ATTR=(ALPHA,PROT,HI) SYSDATE DFLD POS=(02,8),LTH=8,ATTR=(ALPHA,PORT,NORM) DFLD STATUS DISPLAY,POS=(02,28),ATTR=(ALPHA,PROT,HI) DFLD TIME:,POS=(02,56),ATTR=(ALPHA,PROT,HI) SYSTIME DFLD POS=(02,62),LTH=08,ATTR=(ALPHA,PROT,NORM) DFLD ITEM NUMBER:,POS=(06,25),ATTR=(ALPHA,PROT,HI) ITEMNUM DFLD POS=(06,38),LTH=06,ATTR=(NUM,NOPROT,NORM,MOD) DFLD (PF2 - PRINT STATUS HISTORY),POS=(08,24), X ATTR=(NNM,PROT,HI) DFLD (PF3 - RETURN TO MENU),POS=(09,24), X ATTR=(ALPHA,PORT,HI) DFLD ======================================================== ===========,POS=(10,2),ATTR=(ALPHA,PROT,HI) DFLD STATUS CODE:,POS=(11,02),ATTR=(ALPHA,PROT,HI) STCODE DFLD POS=(11,15),LTH=01,ATTR=(ALPHA,PROT,NORM) DFLD STATUS DATE IN:,POS=(11,19),ATTR=(ALPHA,PROT,HI) STDTIN DFLD POS=(11,35),LTH=06,ATTR=(ALPHA,PROT,NORM) DFLD STATUS DATE OUT,POS=(11,44),ATTR=(ALPHA,PROT,HI) STDTOUT DFLD POS=(11,61),LTH=06,ATTR=(ALPHA,PROT,NORM) DFLD STATUS DESCRIPTION: ,POS=(13,02), X ATTR=(ALPHA,PROT,HI) STDESC DFLD POS=(13,22),LTH=20,ATTR=(ALPHA,PROT,NORM) FMTEND ABCISTAT MSG TYPE=INPUT,SOR=(ABCSTA,IGNORE),OPT=1,NXT=ABCOSTAT SEG MFLD (PFKEYSOO,'ABCPSTAT '),LTH=14,JUST=L,ATTR=NO MFLD ITEMNUM,LTH=06,JUST=R,ATTR=NNO,FILL=X'40' MSGEND ABCOSTAT MSG TYPE=OUTPUT,SOR=(ABCSTA,IGNORE),OPT=1,PAGE=NO, X NXT=ABCISTAT SEG MFLD (SYSDATE,DATE2) MFLD (SYSTIME, TIME) MFLD ITEMNUM,LTH=08,JUST=R,ATTR=YES MFLD STCODE,LTH=03,JUST=L,ATTR=YES MFLD STDTIN,LTH=08,JUST-L,ATTR=YES MFLD STDTOUT,LTH=08,JUST=L,ATTR=YES MFLD STDESC,LTH=22,JUST=L,ATTR=YES MSGEND END

IMS DC PROGRAMMING

01/08/2004

Page 40/ 115

Cursor Positioning and Attribute Control from the program

If you code ATTR=YES in a MFLD statement, you should prefix the data area for that field in your programs I/O area with a 2 byte prefix. The first byte if set to XC0 will cause the cursor to be positioned in that field. The next byte can be used to either selectively or completely replace the PROTECTION, SHIFT, and INTENSITY or MDT bits in the field attribute byte. Second byte bits Position Function 0 Not used must be 1 always Override only specific bits if 0 (OR existing bits with following bits) Else override all if 1 (replace existing bits with following bits) 2 0 if unprotected, 1 if protected 3 0 is alpha shift, 1 is numeric shift 4,5 00 is normal intensity, 01 is dark, 10 and 11 is bright 6 not used 7 0 is MDT off, 1 is MDT ON. Absolute cursor positioning, specify for example, DPAGE CURSOR=((3,17,CFIELD)) CFIELD is a MFLD of 4 bytes length. First two bytes will hold the line number and next two will hold the column number. If it is specified in an input MFLD these fields will have the line and column number where the cursor was positioned when the enter key was pressed. If it specifies an output message field, the application can set the line number and column number where the cursor has to be positioned on output.

IMS DC PROGRAMMING

01/08/2004

Page 41/ 115

Simple Flows
/FORMAT MOD
MOD

DOF

DIF

MID

APPLICATION

DOF

MOD

IMS DC PROGRAMMING

01/08/2004

Page 42/ 115

A Simple Menu Application.

RECEIVABLES MENU DATE: MM/DD/YY

PF1 PF2 PF3

ENTER CASH RECEIPTS DISPLAY INVOICE SUMMARY DISPLAY INVOICE DETAILS

PRESS THE INDICATED PF KEY FOR THE FUNCTION YOU WANT TO PERFORM.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX PRINT ON,NOGEN FMT DEV TYPE=(3270,2), FEAT=IGNORE, SYSMSG=ERRMSG, DSCA=X00A0, PFK=(PFKFIELD, /FOR CRO , /FOR DI2O , /FOR DIDSO) DIV TYPE=INOUT DPAGE CURSOR=((1,2)),FILL=PT DFLD RECEIVABLES MENU,POS=(1,2),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD DATE:,POS=(1,65),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(1,72),LTH=9,ATTR=(PROT,ALPHA,HI,NOMOD) DFLD PF1,POS=(5,10),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD ENTER CASH RECEIPTS,POS=(5,15), ATTR=(PROT,ALPHA,HI,NOMOD) DFLD PF2,POS=(6,10),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD DISPLAY INVOICE SUMMARY,POS=(5,15), ATTR=(PROT,ALPHA,HI,NOMOD) DFLD PF3,POS=(7,10),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD DISPLAY INVOICE DETAILS,POS=(7,15), ATTR=(PROT,ALPHA,HI,NOMOD) DFLD PRESS THE INDICATED PF KEY FOR THE,POS=(10,10), ATTR=(PROT,ALPHA,HI,NOMOD) DFLD FUNCTION YOU WANT TO PERFORM,POS=(11,10), ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(23,2),LTH=79,ATTR=(PROT,ALPHA,HI,NOMOD)

MENUDF

X X X X X X

CURDATE

X X X X X

ERRMSG

IMS DC PROGRAMMING FMTEND

01/08/2004

Page 43/ 115

* MENUI

MSG TYPE=INPUT,SOR=(MENUDF,IGNORE),NXT=MENUO SEG MFLD PFKFIELD,LTH=10 MSGEND MSG TYPE=OUTPUT,SOR=(MENUDF,IGNORE),NXT=MENUI SEG MFLD (CURDATE,DATE2) MFLD LTH=1 MSGEND END

* MENUO

Note That the MOD has a MFLD of 1 byte. It isnt used and is needed only because MFS does not allow a output message of length 0.

IMS DC PROGRAMMING

01/08/2004

Page 44/ 115

Another Sample with a Skeleton Program

Operator Keys in /FORMAT DI20. IMS selects the MOD DI20 and the right DOF (based on your terminal type) to output the first screen. The operator now has to enter the invoice number and hit enter.
DISPLAY INVOICE SUMMARY INVOICE: 999999 DATE: 99/99/99 SUBTOTAL: DISCOUNT: SALES TAX: FREIGHT: BILLING: PMTS/ADJS: DUE: DATE: ZZZZZ.99ZZZZZ.99ZZZZZ.99ZZZZZ.99--------ZZZZZ.99ZZZZZ.99--------ZZZZZ.9999/99/99

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The blue back lighted text is output initially. The operator enters the invoice number, back lighted in yellow. The program outputs the inquiry results in the text back lighted in green

The text back lighted in purple is used as an error message area, either by IMS or by the program. The text back lighted in blue are coded as literals in DFLD fields.

The MFS for this is shown below

DI2DF PRINT ON,NOGEN FMT DEV TYPE=(3270,2), FEAT=IGNORE, SYSMSG=ERRMSG,

X X X

IMS DC PROGRAMMING

01/08/2004

Page 45/ 115

DSCA=X00A0 DIV TYPE=INOUT DPAGE CURSOR=((3,12)),FILL=PT DFLD DISPLAY INVOICE SUMMARY,POS=(1,2), X ATTR=(HI,PROT) DFLD DATE:,POS=(1,65),ATTR=(HI,PROT) CURDATE DFLD POS=(1,72),LTH=8,ATTR=(HI,PROT) DFLD INVOICE:,POS=(3,2),ATTR=(HI,PROT) INVNO DFLD POS=(3,12),LTH=6,ATTR=(NUM) DFLD DATE:,POS=(3,21),ATTR=(HI,PROT) INVDATE DFLD POS=(3,28),LTH=8,ATTr=(PROT) DFLD SUBTOTAL:,POS=(3,55),ATTR=(PROT) SUBTOTAL DFLD POS=(3,55),LTH=9,ATTR=(PROT) DFLD DISCOUNT:,POS=(4,41),ATTR=(HI,PROT) DISCOUNT DFLD POS=(4,55),LTH=9,ATTR=(PROT) DFLD SALES TAX:,POS=(5,41),ATTR=(HI,PROT) SALESTAX DFLD POS=(5,55),LTH=9,ATTR=(PROT) DFLD FREIGHT:,POS=(6,41),ATTR=(HI,PROT) FREIGHT DFLD POS=(6,55),LTH=9,ATTR=(PROT) DFLD ---------,POS=(7,55),ATTR=(HI,PROT) DFLD BILLING:,POS=(8,41),ATTR=(HI,PROT) BILLING DFLD POS=(8,55),LTH=9,ATTR=(PROT) DFLD PMTS/ADJS:,POS=(9,41),ATTR=(HI,PROT) PMTSADJS DFLD POS=(9,55),LTH=9,ATTR=(PROT) DFLD ---------,POS=(10,55),ATTR=(HI,PROT) DFLD DUE:,POS=(11,41),ATTR=(HI,PROT) DUE DFLD POS=(11,55),LTH=9,ATTR=(PROT) ERRMSG DFLD POS=(23,2),LTH=79,ATTR=(PROT) FMTEND ********************************************************************** DI2I MSG TYPE=INPUT,SOR=(DI2DF,IGNORE),NXT=DI2O SEG MFLD DI2 ,LTH=8 MFLD INVNO,LTH=6,JUST=R,FILL=C0 MSGEND * DI2O MSG TYPE=OUTPUT,SOR=(DI2DF,IGNORE),NXT=DI2I SEG MFLD (CURDATE,DATE2) MFLD INVNO,LTH=6 MFLD INVDATE,LTH=8 MFLD SUBTOTAL,LTH=9 MFLD DISCOUNT,LTH=9 MFLD SALESTAX,LTH=9 MFLD FREIGHT,LTH=9 MFLD BILLING,LTH=9 MFLD PMTSADJS,LTH=9 MFLD DUE,LTH=9 MFLD ERRMSG,LTH=79 MSGEND END

On the operator entering an invoice number and hitting the enter key, an input message in the following format is generated and queued in the message queue.

IMS DC PROGRAMMING

01/08/2004

Page 46/ 115

The structure of the input message is as follows:LL field which is 4 bytes for PL/I and 2 bytes for COBOL ZZ field of two bytes Data field of variable length. The structure of this field is determined by the MID, but the first eight characters always have the transaction name. The LL field indicates the length of the segment. For PL/I the LL field is 4 bytes (FIXED BINARY(31)) and has the length of the whole segment including LL and ZZ fields minus 2. For COBOL the LL field is 2 bytes (PIC S9(4) COMP) and has the length of the segment. The ZZ field is two bytes. On input the ZZ field is used by IMS and must be left alone. On output the ZZ field may be considered to be 2 single byte fields, Z1 and Z2. The Z1 field is reserved by IMS. The Z2 field may be used to send special commands to the device like ringing a bell, etc. If these features are not used, it must be set to binary zeroes. To determine the structure of the data portion look at the MID definition source.

The first 8 characters of the data part of this message is DI2 which IMS, after referring to its resource definitions identifies as a transaction name. The program corresponding to this transaction is scheduled. When the program starts executing it issues a GU against the I/O PCB (the first pointer passed to the MAIN procedure in PL/I or the first PCB mask in the linkage section). It should receive a blank status code, indicating the input message has been successfully fetched. It is possible that more such messages from other users could be queued behind this message. If no message is available for processing it will receive a QC. Usually MPP programs are coded to fetch more messages after each message is processed and the response sent back to the originating terminal. If a message has more than one segment, issue a GU for the first segment. Then issue GNS for subsequent segment until you get a QD status code. The program designer has to know at coding / design time whether a message can have more than one segment. The MID is where you indicate to IMS that you have more than one segment, by coding more than one SEG macro. In this case the program uses the IM_INVOICE_NO (its a PL/I program) field in the program input data area where the input message segment is read and performs a data base access. The data fetched is moved into field in the output message structure. The output message structure is sent to the terminal via an ISRT call that uses the I/O PCB. As it passes through the MOD, IMS moves the data into appropriate fields in the DOF and the resultant screen is sent back to the terminal.

IMS DC PROGRAMMING

01/08/2004

Page 47/ 115

PROGRAM SKELETON
DI2: PROC(IO_PCB_PTR,DB_PCB_PTR) OPTIONS(MAIN); DCL(IO_PCB_PTR,DB_PCB_PTR) POINTER; DCL PLITDLI ENTRY; DCL 01 IO_PCB_MASK BASED(IO_PCB_PTR), 05 IO_LTERM-NAME CHAR(8). 05 IO_IMS_RSVD CHAR(2). 05 IO_STATUS_CODE CHAR(2). 05 IO_CURR_DATE FIXED DEC(7,0). /* Is a right justified field of form YYDDD */ 05 IO_CURR_TIME FIXED DEC(7,1).
/*

is a right justified field of the form HHMMSST */ 05 IO_MSG_NUMBER FIXED BIN(31). /* The Message sequence number is a running sequence number per terminal since IMS start up */ 05 IO_MOD_NAME CHAR(8). /* If MFS was used to format the input message, contains the MOD name, else spaces */ 05 IO_USER-ID CHAR(8); DCL 01 DB_PCB BASED(DB_PCB_PTR), 05 DBD_NAME CHAR (08), 05 SEGMENT_HIERARCHY_LEVEL_IO CHAR (02), 05 DLI_STATUS_CODE CHAR (02), 05 DLI_PROCESSING_OPTIONS CHAR (04), 05 RESERVED_FOR_DLI CHAR (04), 05 SEGMENT_NAME_FEEDBACK_AREA CHAR (08), 05 LENGTH_OF_KEY_FEEDBACK_AREA FIXED BINARY(31), 05 NUMBER_OF_SENSITIVE_SEGMENTS FIXED BINARY(31), 05 KEY_FEEDBACK_AREA CHAR (NN); DCL 01 INPUT_MESSAGE_IO_AREA, 02 IM_LL FIXED BINARY(31),

IMS DC PROGRAMMING

01/08/2004

Page 48/ 115

02 02 02 DCL 01

IM_ZZ FIXED BINARY(15), IM_TRANSACTION_CODE CHAR(8), IM_INVOICE_NO CHAR(6);

OUTPUT_MESSAGE_IO_AREA, 02 OM_LL FIXED BINARY(31) INIT(160), 02 OM_ZZ FIXED BINARY(15) INIT(0), 02 OM_INVOICE_NO CHAR(6), 02 OM_INVOICE_DATE CHAR(8), 02 OM_PRODUCT_TOTAL PICZZZZZ.99-, 02 OM_CASH_DISC PICZZZZZ.99-, 02 OM_SALES_TAX PICZZZZZ.99-, 02 OM_FREIGHT PICZZZZZ.99-, 02 OM_BILLING PICZZZZZ.99-, 02 OM_PMTS_ADJS PICZZZZZ.99-, 02 OM_BALANCE PICZZZZZ.99-, 02 OM_ERROR_LINE CHAR(79);

DCL C_3 FIXED BINARY(31) INIT(3); DCL C_GU_FUNC DCL C_ISRT_FUNC CHAR(4) INIT(GU); CHAR(4) INIT(ISRT);

CALL PLITDLI ( C_PARM3, C_GU_FUNC, IO_PCB_PTR, INPUT_MESSAGE_IO_AREA ); DO WHILE(IO_STATUS_CODE = ); /* PROCESS THE IM_INVOICE_NO HERE AND SET UP OUTPUT MESSAGE AREA */ CALL PLITDLI ( C_3, C_ISRT_FUNC, IO_PCB_PTR, OUTPUT_MESSAGE_IO_AREA ); /* See if another input message is available for processing */ CALL PLITDLI ( C_3, C_GU_FUNC, IO_PCB_PTR, INPUT_MESSAGE_IO_AREA ); END; /* END OF DO */

IMS DC PROGRAMMING

01/08/2004

Page 49/ 115

IMS DC PROGRAMMING

01/08/2004

Page 50/ 115

Complex Screen Flows

/FORMAT MOD1
MOD1

DOF1

DIF1

MID1

DOF2

MOD2

APPLICATION DIF2 MID2

DOF2

MOD1

By default, the MOD from the same format set as the MID is used when the application sends a reply. You can change the MOD by a fifth parameter in the ISRT call as below:CALL PLITDLI ( PARM_COUNT, C_ISRT_FUNC, IO_PCB_PTR, OUTPUT_MESSAGE_IO_AREA, NEW_MFS_MOD_NAME);

IMS DC PROGRAMMING

01/08/2004

Page 51/ 115

Logical Pages
When MFS formats messages to be sent to a device, it groups message segments into a logical page. You define the logical page using the LPAGE statement within the message statement MSG. IMS will not consider a message complete until all logical pages have been sent. Logical paging is used when multiple pages or displays are needed to satisfy a single request. The PA1 key is used to move forward from one page to the next. Because you will usually deal with single segment messages, you will usually deal with only one logical page. If only one logical page is required, you do not need to specify the LPAGE statement in your format definition. Our sample format did not use the LPAGE statement because it was a single segment message. If you have a message with 400 logical pages that must be completed before the message can be sent, efficiency is lost and machine response becomes slow. Logical paging also increases the complexity of coding MFS and the program. You can use several techniques to present more than one screen of output to a client for a message. Use one of the two techniques described below. A common technique is to have the application program retrieve only enough data to fill one display. The application program stores the current or last retrieved key on a NODISP field of the MFS. Every time the client requests more data, the application uses the key stored in the hidden field to retrieve the new data, and reinitializes the hidden field with the new key value. Another technique is to have a queue database created that will contain the additional pages of the message, if the client needs to see them. The initial request would cause the application program to gather the data for the first few pages to satisfy the request, but would only present the first page to the client. All other pages would be written to the queue database. As the client indicates on the display the desire to see the next, preceding, or any page of the output, your program would retrieve the appropriate page and display it to the client. This way, the program does not have to gather all the pages at one time and can be more efficient. The main drawback using this method is that there is an overhead involved in collecting the information to store on the queue database, and the program will have to be defined as an update program to store information on the queue database. Although different, these techniques have a common characteristic-they allow a more efficient way to present data to a client, as well as a less complex format definition.

IMS DC PROGRAMMING

01/08/2004

Page 52/ 115

An introduction to Logical Pages

Before you try to understand the sample MFS code that uses logical paging, the following needs to be understood. Paging can be implemented using either physical or logical paging. In physical paging, the DFLD statements are coded with the POS parameter as POS=(LL,CC,N) where N is the physical page number. Physical paging is typically used to accommodate different screen sizes. For example a 3270-2 has 24 rows, whereas a 3270-1 has only 12. You then code two DEV statements one for each model. Under the DEV statement for the 3270-2 you have DFLD statements with either no page number or 1, which is the default. Under the DEV statement for 3270-1 you code DFLD statements with both page number 1 as well as 2. MFS will use the right DOF based on the terminal type. By pressing the PA1 key the operator requests for the next page. PA2 purges all remaining pages in the current message and moves on to the next message. You cannot go backwards in physical paging. Alternately you can code a PF key to do the same thing with PFK=(PFKIN,08=NEXTPP,10=NEXTMSGP). In this case PA1 will do the same thing as PF08 and PA2 does the same thing as PF10. Note that NEXTPP and NEXTMSGP are keywords. You can also code multiple input pages by coding the DPAGE statement with MULT=YES. As an example CURSOR=((3,12),(3,17)),MULT=YES. You end the input by associating a PF key with the keyword ENDMPPI. Use the enter key to enter data on each page and advance to the next. Use the PA1 key to skip the current page. A more common approach is the use of logical pages. With Logical Paging, you can do a combination of the following:1. Have one or more DPAGE statements each representing a screen format.

2. Have one or more LPAGE statement in either MID or MOD or both. It is more usual to have it in the MOD. An LPAGE in the MOD maps to a DPAGE like this:SUMLPAGE LPAGE SOR=SUMDPAGE. . .

When you program inserts a segment, MFS understands which LPAGE to use like this:[label] LPAGE SOR=dpagename, COND=(mfldname,{= | < | > | <= | >= },comparison-value

IMS DC PROGRAMMING

01/08/2004

Page 53/ 115

SUMLPAGE LPAGE SOR=SUMDPAGE,COND=(LPAGEID,=,S) SEG LPAGEID MFLD LTH=1 If no match is found the LAST LPAGE is used. Note that the application has to insert a segment with the first data byte set to S to select the SUMLPAGE LPAGE above. On input you can map DPAGE (S) to a MID LPAGE by the SOR keyword as follows:LPAGE SOR=(SUMDPAGE, PAYDPAGE, ADJDPAGE)

You can insert more than one segment from your application against a LPAGE by coding the keyword PAGE=YES on the MSG statement. If you code this MFS inspects the first 5 bytes of any input from the terminal for the following paging commands:= =NNN =L =+NNN =-NNN Move forward one logical page move to page NNN Move to last logical page Move forward NNN logical pages Move backward NNN logical pages

Note that it is easy for MFS to recognize the paging command as they all begin with = which is not a valid character either for a transaction, an LTERM name or a IMS command. The operator can still use PA1 to see the next logical message. PA2 bypasses the rest of the message. Since an indefinite number of segments can be inserted when PAGE=YES is coded on the MSG statement, MFS understands that the page building is complete when the application issues a GU against the IO PCB. You make provision for the 5 bytes needed for the paging command as below:SEG MFLD PAGECMD,LTH=5,FILL=NULL MFLD trancode ,LTH=8 PAGECMD DFLD POS=(22,17),LTH=5,ATTR=(NOPROT,NOMOD,ALPHA) Observe that if the field has not been entered by the operator, it is not transmitted by the terminal. At the MID, since FILL is NULL, the whole field is omitted, leaving the first 8 bytes of the transaction code.

IMS DC PROGRAMMING

01/08/2004

Page 54/ 115

DILDF

SUMDPAGE

CURDATE INVNO INVDATE SUBTOTAL DISCOUNT SALEXTAX FREIGHT BILLING PMTSADJS DUE PAGECMD

ERRMSG * * * PAYDPAGE DPAGE CURSOR=((21,17)),FILL=PT DFLD DISPLAY INVOICE DETAILS PAYMENTS, POS=(1,2),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD DATE:,POS=(1,65),ATTR=(PROT,ALPHA,HI,NOMOD) CURDATE DFLD POS=(1,72),LTH=8,ATTR=(PROT,ALPHA,HI,NOMOD) DFLD INVOICE:,POS=(3,2),ATTR=(PROT,ALPHA,HI,NOMOD) INVNO DFLD POS=(3,12),LTH=6,ATTR=(NOPROT,NUM,NORM,MOD) DFLD DATE:,POS=(3,21),ATTR=(PROT,ALPHA,HI,NOMOD) INVDATE DFLD POS=(3,28),LTH=8,ATTR=(PROT,ALPHA,NORM,NOMOD)

PRINT ON,NOGEN FMT DEV TYPE=(3270,2), FEAT=IGNORE, SYSMSG=ERRMSG, DSCA=X00A0, PFK=(PFKIN, 03=/FOR MENUO, 07==-1 , 08== ) DIV TYPE=INOUT DPAGE CURSOR=((3,12),FILL=PT DFLD DISPLAY INVOICE DETAILS SUMMARY, POS=(1,2), ATTR=(PROT,ALPHA,HI,NOMOD) DFLD DATE:,POS=(1,65),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(1,72),LTH=8,ATTR=(PROT,ALPHA,HI,NOMOD) DFLD INVOICE:,POS=(3,2),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(3,12),ATTR=(NOPROT,NUM,NORM,MOD) DFLD DATE:,POS=(3,21), ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(3,28),LTH=8,ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD SUBTOTAL:,POS=(3,41),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(3,55),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD DISCOUNT:,POS=(4,41),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(4,55),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD SALES TAX:,POS=(5,41),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(5,55),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD FREIGHT:,POS=(6,55),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(6,55),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD ---------,POS=(7,55),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD BILLING:,POS=(8,41),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(8,55),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD PMTS/ADJS,POS=(9,41),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(9,55),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD ---------,POS=(10,55),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD DUE:,POS=(11,41),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(11,55),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD PAGE COMMAND,POS=(21,2),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(21,17),LTH=5,ATTR=(NOPROT,ALPHA,NORM,NOMOD) DFLD PF3=RETURN TO MENU; PF8=NEXT,POS=(22,2), ATTR=(PROT,ALPHA,HI,NOMOD) DFLD POS=(23,2),LTH=79,ATTR=(PROT,ALPHA,NORM,NOMOD)

X X X X X X X

X X

IMS DC PROGRAMMING DFLD DUE DFLD DFLD DFLD DO DFLD DFLD DFLD DFLD ENDDO DFLD TOTALPMT DFLD DFLD PAGECMD DFLD DFLD PDATE PBNKNO PCHKNO PAMT

01/08/2004 CURRENT BALANCE DUE,POS=(3,41), ATTR=(PROT,ALPHA,HI,NOMOD) POS=(3,62),ATTR=(PROT,ALPHA,NORM,NOMOD) DATE BANK NUMBER, POS=(5,2),ATTR=(PROT,ALPHA,HI,NOMOD) CHECK NUMBER AMOUNT, POS=(5,38),ATTR=(PROT,ALPHA,HI,NOMOD) 12 POS=(6,2),LTH=8,ATTR=(PROT,ALPHA,NORM,NOMOD) POS=(6,12),LTH=25,ATTR=(PROT,ALPHA,NORM,NOMOD) POS=(6,38),LTH=16,ATTR=(PROT,ALPHA,NORM,NOMOD) POS=(6,55),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD)

Page 55/ 115 X X X

ERRMSG DFLD * * * ADJDPAGE DPAGE CURSOR=((21,17)),FILL=PT DFLD DISPLAY INVOICE DETAILS ADJUSTMENTS, POS=(1,2),ATTR=(PROT,ALPHA,HI,NOMOD) DFLD DATE:,POS=(1,65),ATTR=(PROT,ALPHA,HI,NOMOD) CURDATE DFLD POS=(1,72),LTH=8,ATTR=(PROT,ALPHA,HI,NOMOD) DFLD INVOICE:,POS=(3,2),ATTR=(PROT,ALPHA,HI,NOMOD) INVNO DFLD POS=(3,12),LTH=6,ATTR=(NOPROT,NUM,NORM,MOD) DFLD DATE:,POS=(3,21),ATTR=(PROT,ALPHA,HI,NOMOD) INVDATE DFLD POS=(3,28),LTH=8,ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD CURRENT BALANCE DUE,POS=(3,41), ATTR=(PROT,ALPHA,HI,NOMOD) DUE DFLD POS=(3,62),ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD DATE TYPE NUMBER AMOUNT, POS=(5,2),ATTR=(PROT,ALPHA,HI,NOMOD) DO 12 ADATE DFLD POS=(6,2),LTH=8,ATTR=(PROT,ALPHA,NORM,NOMOD) ATYPE DFLD POS=(6,14),LTH=1,ATTR=(PROT,ALPHA,NORM,NOMOD) ANO DFLD POS=(6,18),LTH=6,ATTR=(PROT,ALPHA,NORM,NOMOD) AAMT DFLD POS=(6,18),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD) ENDDO DFLD ---------,POS=(19,26),ATTR=(PROT,ALPHA,HI,NOMOD) TOTALADJ DFLD POS=(20,26),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD) DFLD PAGE COMMAND: ,POS=(21,2),ATTR=(PROT,ALPHA,HI.NOMOD) PAGECMD DFLD POS=(21,17),LTH=5,ATTR=(NOPROT,ALPHA,NORM,NOMOD) DFLD PF3=RETURN TO MENU; PF8=NEXT,POS=(22,2), ATTR=(PROT,ALPHA,HI,NOMOD) ERRMSG DFLD POS=(23,2),LTH=79,ATTR=(PROT,ALPHA,NORM,NOMOD) FMTEND EJECT

---------,POS=(19,55),ATTR=(PROT,ALPHA,HI,NOMOD) POS=(20,55),LTH=9,ATTR=(PROT,ALPHA,NORM,NOMOD) PAGE COMMAND: ,POS=(21,2),ATTR=(PROT,ALPHA,HI.NOMOD) POS=(21,17),LTH=5,ATTR=(NOPROT,ALPHA,NORM,NOMOD) PF3=RETURN TO MENU; PF8=NEXT,POS=(22,2), ATTR=(PROT,ALPHA,HI,NOMOD) POS=(23,2),LTH=79,ATTR=(PROT,ALPHA,NORM,NOMOD)

X X

IMS DC PROGRAMMING

01/08/2004

Page 56/ 115

DILI

* * * DILO MSG PAYLPAGE LPAGE SEG MFLD LPAGEID MFLD MFLD MFLD MFLD DO MFLD MFLD MFLD MFLD ENDDO * * * ADJLPAGE LPAGE SEG MFLD LPAGEID MFLD MFLD MFLD MFLD DO MFLD MFLD MFLD MFLD ENDDO MFLD MFLD * SUMLPAGE LPAGE SEG MFLD LPAGEID MFLD MFLD MFLD MFLD MFLD MFLD MFLD MFLD MFLD

MSG TYPE=INPUT,SOR=(DILDF,IGNORE),NXT=DILO LPAGE SOR=(SUMDPAGE,PAYDPAGE,ADJDPAGE) SEG MFLD PAGECMD,LTH=5,FILL=NULL MFLD PFKIN,LTH=10,FILL=NULL MFLD DIL ,LTH=8 MFLD INVNO,LTH=6 MSGEND

TYPE=OUTPUT,SOR=(DILDF,IGNORE),NXT=DILI,PAGE=YES SOR=PAYDPAGE,COND=(LPAGEID,=,P) (CURDATE,DATE2) LTH=1 INVNO,LTH=6 INVDATE,LTH=8 DUE,LTH=9 12 PDATE,LTH=8 PBNKNO,LTH=25 PCHKNO,LTH=16 PAMT,LTH=9

SOR=ADJDPAGE,COND=(LPAGEID,=,A) (CURDATE,DATE2) LTH=1 INVNO,LTH=6 INVDATE,LTH=8 DUE,LTH=9 12 ADATE,LTH=8 ATYPE,LTH=1 ANO,LTH=6 AAMT,LTH=9 TOTALADJ,LTH=9 ERRMSG,LTH=79 SOR=SUMDPAGE,COND=(LPAGEID,=,S) (CURDATE,DATE2) LTH=1 INVNO,LTH=6 INVDATE,LTH=8 SUBTOTAL,LTH=9 DISCOUNT,LTH=9 SALESTAX,LTH=9 FREIGHT,LTH=9 BILLING,LTH=9 PMTSADJS,LTH=9

IMS DC PROGRAMMING

01/08/2004

Page 57/ 115

MFLD DUE,LTH=9 MFLD ERRMSG,LTH=79 MSGEND END

MFS Interfaces
In this section you were introduced to the basic features of MFS. MFS consists of many features, and at times coding a format can be complex and laborious. To aid in the creation of MFS formats, many user-friendly interfaces have been developed, either inhouse or by vendors, that significantly reduce the time and complexity of creating a format. Check with your installation as to whether such an interface is available to you. If there is one, it is recommended that you use it. There may be times when an interface does not have the capability to take advantage of a particular feature of MFS, and it becomes necessary for you to alter the output of the MFS interface.

Testing and Debugging Aids

Each source member should assemble with a return code of 0. If you find that you have a return code greater than 0, refer to the following list for possible causes: 1 Find on the word WARN. If the message states that the DFLD may cause a buffer lock on a remote 3270 device, this means a DFLD in pos (1,2) does not have ATTR=NUM. Find on the character SC=(Severity Code). The assembler will place a position marker ('1') under the offending piece of code and provide a list of the expected values. Find on the word OVERLAP. These errors are paired up and are normally caused when the attribute byte requirement of the 3270 device is forgotten. Find on the word SYMBOL. You will be placed at the DPAGE/LPAGE symbol reference table. If four asterisks follow a MSG or FMT in the table, it means there is normally a discrepancy between a DFLD label used by an MFLD. In most cases, this is a typo.

3 4

IMS DC PROGRAMMING

01/08/2004

Page 58/ 115

IMS Online Coding

back

When you complete this section, you will have an understanding of what is required in an application program to perform interactive processing in the IMS online environment. This section on IMS online coding covers the following: Programming in the IMS online environment Online communication: Data Base Processing (DB) Data Communications Processing (DC) Combination Processing (DB/DC) Input/Output Program Communication Block (I/O PCB) DL/I Call Format I/O PCB Mask Message Processing - Input Message text I/O Areas Retrieving messages using DL/I Message Processing - Output Sending messages using DL/I Purge Call Dynamic Attribute Modification Message Processing - Alternate Alternate PCB Mask Change Call

Conversational programs

IMS DC PROGRAMMING

01/08/2004

Page 59/ 115

Programming in the IMS Online Environment

By now you should have an understanding of the IMS online environment, as well as how to design terminal screens using the IMS Message Format Service. You will now learn what it takes, as a systems engineer, to code online IMS programs that can perform the input/output processing of data transmitted via physical devices (such as 3278 terminals). Let's review the data base (DB) portion of IMS. Every IMS application program uses a Program Specification Block (PSB) to control its access to IMS resources. When the resources are databases, the PSB contains a Program Communication Block (PCB) for each database that the application program needs to access. A data base-type PCB not only specifies the database or Data Base Descriptor (DBD), you need to access, but also those segments within the database you need to access. The segment specification provides IMS with your logical view of the database. Additionally, your access rights or processing options could be specified at the PCB and/or segment level. Processing options include the ability to insert, delete, retrieve, or replace segments within the database. For IMS to logically tie databases to your application program through the PSB, you had to specify a pointer (address) for each PCB in the PSB. The order of the pointers in your program determined which database IMS would access, and therefore had to coincide with the order of the PCBs in the PSB.

Online Communication
The online communication will be done by DL/I through the I/O PCB. Communicating with a terminal device is not different from communicating with a database. Instead of processing data from a database, you will be processing messages from a message queue. IMS provides for three methods of processing: Data Base (DB), Data Communication (DC), and DB/DC, which is a combination of the two. Each is explained in detail below.

Data Base Processing

The example below shows an IMS application program using only the DB portion of IMS. In this case, the program accesses IMS databases and only requires the DB functions of IMS. This is typical of IMS batch applications.

IMS DC PROGRAMMING

01/08/2004

Page 60/ 115

IMS Data Base (Batch Programs)

APPLICATION

PROGRAM

DL/I

OS FILES

IMS

DATA BASES

The application program also has access to OS files with this type of processing.

Data Communications Processing

The example below shows an IMS application program using only the DC portion of IMS. In this case, the program accesses only the IMS message queues, and only requires the DC portion of IMS.

IMS DC PROGRAMMING

01/08/2004

Page 61/ 115

Message Processing Programs APPLICATION PROGRAM

DL/I

IMS

MESSAGE QUEUE

Note: Even though the application program only uses the DC portion of IMS, it cannot be installed without another data base management system (DBMS) such as DB2. The application program does not have access to OS or data bases files with this type of processing.

Combination Processing
The example below shows an IMS application program using the DB and DC portions of IMS. This is the most frequently used method of processing for online IMS programs. Typically, you will use the DC portion to communicate with the client, and the DB portion to gather the data to present information back to the client.

IMS DC PROGRAMMING

01/08/2004

Page 62/ 115

IMS DB/DC-MPP and Batch Message Processing Programs

APPLICATION PROGRAM

DL/I

IMS

MESSAGE QUEUE

OS FILES

IMS DATA BASES

Note: A BMP application program can access OS files. The MPP application program cannot access OS files.

Input/Output Program Communication Block

Typically, the data in an IMS database is reported from, and updated by, what is considered a batch-processing environment. Many clients, however, require reports and updates more frequently than the cyclical batch processing can provide. IMS was also designed with this need in mind. IMS provides for an interactive immediate access to the physical data. This is the Data Communications (DC) part of IMS. The I/O PCB provided by IMS that allows your program to process messages is not coded in your PSB. Instead, IMS assumes that because this is a message-processing program, the first PCB pointer, (or for COBOL, the first parameter on the using statement) is for the I/O PCB or the message queue. Any need to access other online IMS resources will require will require the coding of a Tele Processing (TP) PCB in the

IMS DC PROGRAMMING

01/08/2004

Page 63/ 115

PSB and as a result, the addition of the pointer or parameter in the application program. These TP PCBs must be coded in the PSB before any database PCBs. Accessing resources other than databases was introduced in the environment section, when it was stated that a physical device was the originating point of most IMS messages. In addition, physical devices that did not create a message can be accessed. Accessing other physical devices, such as a printer or a different LTERM, is similar to how you process messages from the message queue. The easiest way to think of accessing these resources is to consider the other resource as another message queue. These other message queues are called alternate I/O PCBS and will be discussed in a subsequent section. Figure 4-1 shows how the I/O, and data base PCB pointers are coded in an application program. PL/I OLPGM: PROC (L_IO_PCB_PTR, L_DB1_PCB_PTR, Data Base PCB Pointer OPTIONS (MAIN); COBOL ENTRY 'DLITCBL' USING L-IO-PCB, L-DB1-PCB, L-DBn-PCB. I/O PCB Data Base PCB I/O PCB Pointer Data Base PCB Pointer

L_DBn_PCB_PTR)

Data Base PCB

Figure 4-1. Application Program PCB Specification

IMS DC PROGRAMMING

01/08/2004

Page 64/ 115

DL/I Call Format

Because DL/I is used to communicate and process the message queues, you need to know the format of the DL/I DC call to the message queues. Figure 4-2 shows this format. PL/I CALL PLITDLI (W_PARM_CNT, C_FUNC_CODE, L_PCB_PTR, (L_IO_PCB_PTR) W_MESSAGE_IO, I/O Area W_FMT_DEST); Name (optional) COBOL CALL 'CBLTDLI' USING W-PARMCount (optional) C-FUNCCode L- PCB(L-IO-PCB) W-MESSAGEArea W-FMT-DEST. (optional) Parameter Count Function Code I/O PCB Message (screen) Format MOD CNT, CODE, MASK, IO, Parameter Function I/O PCB

Message (screen) I/O Format MOD Name

Figure 4-2. DL/I Message Call Format The fact we are calling DL/I to process our request to the message queue means the call must follow the same format as if we were processing a database. Each call parameter is described below. PARM_CNT This parameter is the parameter count. It is a binary full word (for PL/I and half word for COBOL) that has a value equal to the number of parameters passed to the DL/I call, not including the parm count itself. This is a required parameter for PL/I, optional for COBOL. Although it is an optional parameter for COBOL, we will use it in all the text examples. The PL/1 DCL is FIXED BIN(31). For COBOL it is PIC S9(9) COMP. FUNC_CODE This parameter is the function code. It must be a character string four bytes in length, and specify the type of function DL/I should perform to the message queue: retrieve, insert, purge, and so on. Figure 4-3 shows a table of common DL/I DC function codes and their descriptions.

IMS DC PROGRAMMING

01/08/2004

Page 65/ 115

DL/I DC Function Code CHNG (CHaNGe) GU (Get Unique) GN (Get Next) ISRT ( InSeRT) PURG (PURGe)

Function Description Allows you to set the destination on a modifiable alternate PCB. Retrieves the first segments of a new message. Retrieves the next message segment of a multisegmented message. Inserts a message into the message queue. Enqueues messages from a PCB to their destinations.

Figure 4-3, Common DL/I DC Function Codes PCB_PTR This parameter is either the I/O PCB or alternate PCB pointer name. This name must be the same name used in the main PROCEDURE statement of a PL/I program, or the same name used in the LINKAGE SECTION and ENTRY statement of a COBOL program. This is a required parameter in all DL/I calls. MESSAGE_IO This parameter specifies the starting address of the input area for input messages, or the starting address for output messages. For input messages, the allocated area must be large enough to hold the entire message, or storage overlay may occur. FMT_DEST This is an optional parameter. It is a character string eight bytes in length containing one of the following: if FUNC CODE is ISRT, this must be a MOD name; if FUNC CODE is CHNG, this could be either the LTERM name of an alternate device such as a printer or another terminal, or it could be a Transaction Name. I/O PCB Mask Whenever a call is made to DL/I, information about the call is provided to your application program through the PCB pointer used in the call. (It is assumed that you are experienced with using DL/I to process IMS databases, and therefore with the database PCB I/O area or PCB mask.) Specify the I/O PCB pointer in your DL/I call the same way you specify the database PCB pointer. As with databases, DL/I will provide you with an address to a PCB I/O area. The content of the PCB I/O area for

IMS DC PROGRAMMING

01/08/2004

Page 66/ 115

the I/O PCB is different from that of a data base PCB. Figure 4-4 shows how the I/O PCB mask should be coded in your application program. PL/I DCL L_IO_PCB_PTR POINTER: DCL 01 L_IO_PCB_MASK BASED(L_IO_PCB_PTR), 05 L_IO_LTERM-NAME 05 L_IO_IMS_RSVD 05 L_IO_STATUS_CODE 05 L_IO_CURR_DATE 05 L_IO_CURR_TIME 05 L_IO_MSG_NUMBER 05 L_IO_MOD_NAME 05 L_IO_USER-ID COBOL LINKAGE SECTION 01 L -10-PCB. 05 L-IO-LTERM-NAME 05 L-IO-IMS-RSVD 05 L-IO-STATUS-CODE 05 L-IO-CURR-DATE 05 L-IO-CURR-TIME 05 L-IO-MSG-NUMBER 05 L-IO-MOD-NAME 05 L-IO-USER-ID Figure 4-4. I/O PCB Mask The following is a detailed description of each element in the mask: LTERM NAME This field contains the LTERM name of the device that sent the message. It is a string of characters eight bytes in length. IMS RSVD These two bytes are reserved for IMS/VS. STATUS CODE This field will contain the status code of the call. It is a string of characters two bytes in length. CURR DATE

CHAR(8), CHAR(2), CHAR(2), FIXED DEC(7,0), FIXED DEC(7,1), FIXED BIN(31), CHAR(8), CHAR(8);

PIC PIC PIC PIC PIC PIC PIC PIC

X(8). X(2). X(2). S9(7) COMP-3. S9(6)V9 COMP-3. S9(9) COMP. X(8). X(8).

IMS DC PROGRAMMING

01/08/2004

Page 67/ 115

This field contains the current data that the entire message was sent. It is in Julian data format, YYDDD, and is a four-byte, right-justified, packed-decimal field. CURR TIME This field contains the current time the entire message was sent. It is a four byte, right-justified, packed decimal field in the HHMMSST format. MSG NUMBER This field is binary, four bytes in length, and contains the sequence number assigned by IMS. Sequence numbers are assigned by LTERM and are continuous, based on the current IMS start up. MOD NAME This field contains the Message Output Descriptor name, if MFS was used to format the message. If MFS was not used, the field is blank. It is a character string of eight bytes. USER ID This field is a character string of eight-bytes that contains a unique user identification, and is used in conjunction with IMS sign-on security facilities.

Message Processing - Input

You have learned that the communication between an IMS online application and a client involves the transmitting of messages back and forth. These messages are always queued to wait for processing. Remember from Section 1, there are three types of messages that can be transmitted between a terminal and IMS. A brief review of the three types is as follows: If the first character of the input message is a slash (/), this is an IMS operator command. If the first eight bytes of the message start with an LTERM code, this is a message switch. If the first eight bytes of the input message are a transaction code, IMS will schedule the application program associated with the transaction code for execution.

Retrieving Messages Using DL/I

Making retrieval calls to the message queue is similar to making a retrieval call to a database. Use a GET function to the I/O PCB, instead of a data base PCB, to retrieve a message destined for your program. Remember, the first PCB pointer specified in your ENTRY statement (for COBOL) or PROC statement (for PL/I) is considered by IMS to be the I/O PCB.

IMS DC PROGRAMMING

01/08/2004

Page 68/ 115

Get Unique Call

To retrieve the first segment of a message from the message queue, you must issue a Get Unique (GU) call. The skeleton code shown on the next several pages reflects the DL/I code necessary to retrieve messages from the message queue. Note: IMS requires that an MPP issue at least one GU call to the I/O PCB to retrieve a message. If the MPP does not issue as least one call to the I/O PCB, IMS will not permit the MPP to end successfully. (The program will abend with a user 462). It is efficient to have the first DL/I call in an MPP issue the GU because when IMS schedules the application program into the dependent region, IMS also transfers the first segment of the first message into the region. If the MPP issues any other DL/I call, IMS has to bring the message back into the region, and the priming efficiency is lost. The following figure 4-7 indicates the logic for retrieving messages via a QC (status code) loop. PL/I OLPGM: PROC ( L_IO_PCB-PTR. L_DB_PCB_PTR ) OPTIONS ( MAIN ) REORDER: CALL PLITDLI (C_PARM3, C_GU_FUNC, L_IO_PCB_PTR, W_INPUT_MESSAGE); /*MAINLINE*/ DO WHILE (L_IO_STATUS_CODE = ' '); CALL S100_INIT_VAR; /** RESET WORK AREAS, IO AREAS **/ CALL S300_PROCESS_MESSAGE: CALL PLITDLI ( C_PARM3, C_GU_FUNC, L_IO_PCB_PTR, W_INPUT_MESSAGE );

IMS DC PROGRAMMING

01/08/2004

Page 69/ 115

END;

/* DO WHILE L_IO_STATUS_CODE = ' ' */

IF L_IO_STATUS_CODE = 'QC' THEN; ELSE CALL S800_ERROR; Figure 4-7. QC COBOL. S200-NEXT-SEG. CALL 'CBLTDLI' USING C-PARM3, C-GN-FUNC, L-IO-PCB, W-INPUT-MSG-NEXT. IF L-IO-STATUS-CODE = C-BLANKGOOD PERFORM S250-PROCESS-SEGMENT ELSE IF L-IO-STATUS-CODE = C-QD-NO-MORE NEXT SENTENCE ELSE PERFORM S900-ERROR-RTN END-IF END-IF Figure 4-10. Get Next Message Processing - COBOL. Let's examine the flow of logic to process the second and subsequent segments of a message. After determining that at least one segment of a message has been retrieved (successful GU call), and there is a multi segmented message to process, issue a GN call to the I/O PCB. Test the status code of the GN call. If the status code is blank, you can process the data retrieved from the segment, or check to see if other segments exist for the message by issuing subsequent GN calls until a QD status is returned. If the status code is QD, there are no more segments for this message, and you can now perform logic to process the entire message. Loop GU Message Processing - PL/I

IMS DC PROGRAMMING

01/08/2004

Page 70/ 115

Message Processing - Output

Once your application program has processed an input message, it will output a message to the device that originated the message. In this case, the application program will send a message to the message queue. To do this, the output message, like the input message, must follow a certain format. Let's assume that our application program created a message to be sent back to the client. The general format of an output message is shown in Figure 4-11, and is defined as follows:

PL/I DCL 01 W_OUTPUT_MESSAGE, 05 W_OM_LL, 05 W_OM_ZZ, 05 W_MESSAGE_TEXT; COBOL 01 W-OUTPUT-MESSAGE. 05 W-OM-LL 05 W-OM-ZZ 05 W-MESSAGE-TEXT

FIXED BIN(31) INIT(??). FIXED BIN(15) INIT(??). CHAR(NNNN);

PIC S9(4) COMP VALUE ???. PIC S9(4) COMP VALUE ???. PIC X(NNNN).

Figure 4-11. Format of an Output Message Although it begins the same as that for an input message, the difference will be that we have many more fields to send back to the MFS for formatting. Remember that we are going to be sending attribute information to the screen (ATTR=YES on each MFLD of MOD). Remember that for input messages, IMS calculated the LL and determined the ZZ. For output messages, the application program must provide IMS with a valid LL and a valid ZZ prior to sending the output message to the message queue. Let's look at the MOD to review what fields we are going to send to the screen.
****************************************************************** ****** * MESSAGE OUTPUT DESCRIPTOR (MOD) * *********************************************************************** * ABCOSTAT MSG TYPE=OUTPUT,SOR=(ABCSTA,IGNORE),OPT=1,PAGE=NO, X NXT=ABCISTAT SEG

IMS DC PROGRAMMING

01/08/2004

Page 71/ 115

MFLD (SYSDATE,DATE2) MFLD (SYSTIME,TIME) MFLD ITEMNUM,LTH=08,ATTR=YES MFLD STCODE,LTH=03,ATTR=YES MFLD STDTIN,LTH=08,ATTR=YES MFLD STDOUT,LTH=08,ATTR=YES MFLD STDESC,LTH=22,ATTR=YES MSGEND END

Based on this definition, we would define a detailed output area in our program as shown in Figure 4-12. Note that the output area specifies in the LL and ZZ valid values for each field. PL/I DCL 01 W_OUTPUT_MESSAGE. 05 W_OM_LL FIXED BIN(31) INIT(53), 05 W_OM_ZZ FIXED BIN(15) INIT(1), 05 W_OM_MESSAGE_TEXT, 10 W_OM_ITEM_MFLD, 15 W_OM_AITEM CHAR(02) INIT(' '), 15 W_OM_ITEM CHAR(06) INIT(' '), 10 W_OM_STCODE_MFLD, 15 W_OM_ASTATUS CHAR(02)INIT(' '), 15 W_OM_STATUS CHAR(01)INIT(' '), 10 W_OM_STDTIN_MFLD, 15 W_OM_ADATEIN CHAR(02)INIT(' '), 15 W_OM_DATEIN CHAR(06)INIT(' '), 10 W_OM_STDTOUT_MFLD, 15 W_OM_ADATEOUT CHAR(02)INIT(' '), 15 W_OM_DATEOUT CHAR(06) INIT(' '), 10 W_OM_STCESC_MFLD, 15 W_OM_ADESC CHAR(02)INIT(' '), 15 W_OM_DESC CHAR(20) INIT(' '); COBOL 01 W-OUTPUT-MESSAGE. 05 W-OM-LL PIC S9(4) VALUE +53 COMP. 05 W-OM-ZZ PIC S9(4) VALUE +1 COMP. 05 W-OM-MESSAGE-TEXT. 10 W-OM-ITEM-MFLD. 15 W-OM-AITEM PIC S9(4) VALUE +0 COMP. 15 W-OM-ITEM PIC X(06) VALUE ' '. 10 W-OM-STDCODE-MFLD. 15 W-OM-ASTATUS PIC S9(4) VALUE +0 COMP. 15 W-OM-STATUS PIC X VALUE ' '. 10 W-OM-STDTIN-MFLD. 15 W-OM-ADATEIN PIC S9(4) VALUE +0 COMP. 15 W-OM-DATEIN PIC X(06) VALUE ' '. 10 W-OM-STDOUT-MFLD.

IMS DC PROGRAMMING

01/08/2004

Page 72/ 115

15 W-OM-ADATEOUT PIC 15 W-OM-DATEOUT PIC 10 W-OM-STDESC-MFLD. 15 W-OM-ADESC PIC 15 W-OM-DESC PIC

S9(4) VALUE +0 COMP. X(06) VALUE ' '. S9(4) VALUE +0 COMP. X(20) VALUE ' '.

Figure 4-12. Message OUTPUT Area Definition Let's review how this output area maps to the MOD. W-OM- LL This field specifies the length of the message. This is what tells IMS how much data to take from your program as a message. It must be a binary field because IMS will interpret the first two bytes as binary, (first four bytes in PL/1) in order to determine how much data to take from the application program. This must be the length of all the fields (minus 2 if PL/1), including the LL and the ZZ. W-OM-ZZ This should contain the value 1 unless using advanced MFS device control features. (A value of 0 is treated by MFS as a 1.) W-OM-AITEM This field represents the attribute bytes for the next field to follow in the message. In the MOD, it is included as part of the MFLD with DFLD ITEMNUM. WOM-ITEM Item Number is a field on the screen. It is six bytes long. In the MOD, it is the last six bytes of the MFLD with label ITEMNUM. W-OM-ASTATUS This field represents the attribute bytes for the next field to follow in the message. In the MOD, it is included as part of the MFLD with DFLD STCODE. W-OM-STATUS Status Code is a field on the screen. It is one byte long. In the MOD, it is the last byte of the MFLD with DFLD STATUS. W-OM-DATEIN This field represents the attribute bytes for the next field to follow in the message. In the MOD, it is included as part of the MFLD with DFLD STDTIN. W-OM -DATEIN Status Date In is a field on the screen. It is six bytes long. In the MOD, it is the last six bytes Status Date In is a field on the screen. It is six bytes long. In the Mod, it is the last six bytes of the MFLD with DFLD STDTIN.

IMS DC PROGRAMMING

01/08/2004

Page 73/ 115

W-OM-ADATEOUT This field represents the attribute bytes for the next field to follow in the message. In the MOD, it is included as part of the MFLD with DFLD STDOUT. W-OM-DATEOUT Status Date Out is a field on the screen. It is six bytes long. In the MOD, it is the last six bytes of the MFLD with DFLD STDTOUT. W-OM-ADESC This field represents the attribute bytes for the next field to follow in the message. This field, plus the following field, combine to map to the last MFLD with DFLD label STDESC. W-OM-DESC Status Description is a field on the screen. It is twenty bytes long. In the MOD, it is the last 20 bytes of the DFLD STDESC. Note: The system date and time are not coded as part of the output message area in the program because they are inserted into the message by MFS when the MOD and DOF are combined to create the formatted screen.

Sending Messages Using DL/I

To send a message to the message queue, you use an ISRT call to the I/O PCB, similar to the ISRT call to a database PCB, as shown in Figure 4-13. Insert Call PL/I ( . . . BUILD OUTPUT MESSAGE AREA . . . ) CALL PLITDLI (C_PARM3, C_ISRT_FUNC, L_IO_PCB_PTR, W_OUTPUT_MESSAGE); COBOL ( . . . BUILD OUTPUT MESSAGE AREA . . . ) CALL 'CBLTDLI' USING C - PARM3. C - ISRT FUNC, L - IO PCB, W - OUTPUT - MESSAGE. Figure 4-13, Insert to Message Queue

IMS DC PROGRAMMING

01/08/2004

Page 74/ 115

It has been mentioned that a message is made up of one or more segments. If you need to insert a multi-segmented message to the queue, you will need to add additional insert calls using the appropriate I/O areas. The only acceptable status code for the ISRT call is blank. All others should be treated as errors and handled in an error routine. Another variation of an ISRT call is shown in Figure 4-16. In this example, the ISRT call is inserting a message to the message queue, but specifying a different MOD than the originating message would have used. This is useful when your program may need to perform several functions based on a standard input MID, as in the case where one application program may send several different screens back to a client based on selection data entered. It can also be used to send a formatted screen back to the client if an unformatted method was used to create the message. When specifying a MOD in an ISRT call, it is important to keep in mind that you can only specify the MOD in the first call to the PCB. All subsequent ISRT calls to the same PCB must not specify the MOD unless a COMMIT POINT has occurred. (See Commit Points in a Message Processing Program for a discussion on commit points.) PL/I ( . . . BUILD OUTPUT MESSAGE AREA . . . ) CALL PLITDLI (C_PARM4, C_ISRT_FUNC, L_IO_PCB_PTR, W_OUTPUT_MESSAGE, C_ABCOSTAT); <--------- optional parameter COBOL ( . . . BUILD OUTPUT MESSAGE AREA . . . ) CALL 'CBLTDLI' USING C - PARM4, <--------- optional parameter C - ISRT FUNC, L - IO PCB, W - OUTPUT MESSAGE, C ABCOSTAT. <--------- optional parameter Figure 4-16 insert to Message Queue with Different MOD

Commit Points in an MPP

One thing to plan for in designing an MPP is resource integrity. IMS will not allow other application programs to access data your MPP has updated until your MPP reaches a

IMS DC PROGRAMMING

01/08/2004

Page 75/ 115

commit point. At a commit point, IMS treats as permanent any changes to databases and to the I/O PCB. Until your MPP reaches a commit point, IMS holds any output messages in a buffer area. This is in case of an abnormal termination, the message is not sent to a terminal or application program by mistake and any database updates are backed out and not made permanent. Three things in the execution of your MPP may cause a commit point to occur. The successful termination of your application program.

A Basic Checkpoint call. MPPS do not support symbolic checkpoint/restart. A big drawback in having an MPP issue a checkpoint call is that IMS also issues an internal GU to the message queue. Your program must be able to handle multiple input messages before the current message is completely processed. A GU to the message queue may cause a commit point. If the MPP has MODE=SNGL on the TRANSACT macro at system definition time, a commit point is reached when a GU to the I/O to the I/O PCB is issued. If the MODE=MULT, then a GU to the I/O PCB does not cause a commit point. For further discussion of commit points in an MPP, refer to the IMS/VS Application Programming Guide.

Purge Call
When your program terminates, or reaches a commit point, output messages are sent to their destination. At times, a program may need to send messages through another PCB (usually an alternate PCB) to different destinations before reaching a commit point. In this situation, you can use the PURG call to tell IMS when each message is complete and to send it to its destination. You can now issue other ISRT calls to the same TP PCB. An example of a PURG call is shown in Figure 4-17. Note : The PURG call can only be used for TP PCBs. PL/I CALL PLITDLI (C_PARM2, C_PURG_FUNC, L_IO_PCB_PTR); COBOL CALL 'CBLTDLI' USING C-PARM2, *optional parameter* C-PURG-FUNC, L-IOPCB. Figure 4-17 Purge call to I/O PCB

IMS DC PROGRAMMING

01/08/2004

Page 76/ 115

The PURG call can also be used to ISRT a new message. If you increment the parameter count by 1 and add an output message area after the PCB pointer (or PCB mask in COBAL). IMS will issue the PURG call and issue an ISRT call with the specified output message area. Because it does an ISRT call for you, you can add the optional MOD name to the call as the last parameter. Increment the parameter count by a further 1.

Dynamic Attribute Modification

There are times when you will want to change the way field is displayed on the device that is different from the way it is defined in the DOF. For example, you might want to highlight a field that is in error, or to perhaps position the cursor at the first in error. or both. Whatever the reason, you have the ability to dynamically change the field attribute bytes before sending the message to the device, providing your MOD specified ATTR=YES. Because the attribute bytes are binary, a table of bit settings for the two attribute bytes is shown in Figure 4-18. The bits are numbered 0 through, in a left to right manner, when defining each attribute's bytes, 0 and 1. BITS 0-1 BITS 2-7 BIT 0 BIT 1 BIT 2 BIT 3 BIT 4 BIR 5 BIT 6 BIT 7 BYTE 0 If 11, the cursor is placed in the first position of the field ; otherwise code 00, which placed the cursor at the first input field on the screen. Must be 0. BYTE 1 Must be 1. If 1 replace the DOF attribute with the attribute value from the output message area. If 0 - the DOF attributes is to be logically ORD with the value from the output message area. If 1 the field is protected If 0 the field is unprotected. If 1 the field is considered numeric If 0 the field is considered alphanumeric. If 1 the field is displayed in high intensity. If 0 the field is displayed in normal intensity. If 1 the field is not displayed (hidden). If 0 the field is displayed If 1 the field is light pen detectable. If 0 the field is not light pen detectable. If 1 the MDT will be turned on in the DOF. If 0 the MDT will not be turned on unless the field is modified on the screen. Figure 4-18. Table of Attributes Bytes Settings These are by no means all the possible attributes, but the most commonly used, Extended attributes, requiring an additional two bytes and controlling such attributes as color, blinking, underlining, and reverse video, will not be covered in this course.

IMS DC PROGRAMMING

01/08/2004

Page 77/ 115

You can use any combination in a single attribute, as long as they are not mutually exclusive. That is to say, you cannot have a field that is both PROTECTED and NONPRROTECTED at the same time, but you can have a field that is PROTECTED and HIGH INTENSITY at the same time. To specify an attribute for a field that is protected, and you need to make the field both protected and high intensity, you can add the high intensity to the field by combining the fields through the use of the logical OR. Let's look at an example. BYTE 0 BYTE 1 00000000 10100000 (protected) DOF attribute 00000000 10001000 (High Intensity) output message attribute _________________ 00000000 10101000 (Protected and high Intensity) screen attribute. This would translate out to a hex value of A8, and a decimal value of +168. This resultant attribute will be used by MFS to display the field on the screen. Now that you know the bit settings to accomplish the various display attributes, let's see how this is performed in a program. In the first example, we will see how to initialize an attribute that will cause a field to be hidden. (non display) and pre modified. PL/I DCL C_HID_MOD BIT(16) INIT('0000000010000101'B): COBOL 01 C-HID-MOD PIC S9(4) VALUE + 133 COMP. Since you cannot twiddle bits in COBOL, you need to perform Base Number arithmetic. The binary value, as we see in the PL/I example, is 0000000010000101. This binary number converts to 0085 in HEX, or + 133 in decimal. We can now code the appropriate COBOL statement. You probably will not have to do all this conversion for COBOL, as most installations have a predefined table for the COBOL attribute values. Let's see a more complex example for COBOL. We want to define an attribute for a hidden field and have the cursor placed at that field. In this example, it will also be pre-modified. PL/I DCL C_HID_CUR_MOD BIT(16) INIT('1100000010000101'B);

IMS DC PROGRAMMING

01/08/2004

Page 78/ 115

COBOL 01 C-HID-CUR-MOD PIC S9(5) VALUE -16251 COMP. Again, we must do Base Number conversion. This time, however, we see the high order bit is on, which means a negative number. In order to evaluate this, we must first get the twos complement. 1100000010000101 0011111101111011 +1 ________________ 0011111101111011 original value twos complement add one binary result

The hex value is 3F7B, or a decimal value of 16,251; do not forget that it is negative, therefore it would be coded as -16251. Notice that the size must increase from S9(4) to S9(5) to hold the value. This is fine, since only the last two bytes contain the value, and movement of this field to a two-byte attribute field will truncate the two high-order bytes, which are not needed.

IMS DC PROGRAMMING

01/08/2004

Page 79/ 115

Message Processing - Alternate PCB

Normally, when you write an IMS online application program, you will communicate back and forth with the sending device. What if there is a need to send a message to a device other than the sending device, or to schedule another transaction based on input from the sending message? . IMS provides for these situations through the use of alternate PCBs. (Remember, PCBs are specified in the PSB.) The I/O PCB is not included in the PSB; however, alternate PCBs must be, and must be coded before any database PCBs. Depending on your needs, an alternate PCB in several ways. The various methods are shown in Figure 4-22.

Hard coded Destination

PCB TYPE=TP,NAME=tranname.... PCB TYPE=DB,NAME=dbdname.... PSBGEN LANG=....PSBNAME=...

HARDCODED LTERM
PCB TYPE=TP,LTERM=ltermname.... PCB TYPE=DB,NAME=dbdname.... PSBGEN LANG=....PSBNAME=...

MODIFIABLE PCB
PCB TYPE=TP,MODIFY=YES.... PCB TYPE=DB,NAME=dbdname.... PSBGEN LANG=....PSBNAME=... Figure 4-22. Examples of PSBS with Alternate PCBs The preferred method is the modifiable PCB. The other methods explicitly specify an LTERM or transaction name. If an LTERM or transaction changes, the PSB needs to be changed and regenerated. With the modifiable PCB, you can dynamically specify from within the application program the LTERM or transaction you want to work with, instead of changing the PSB.

IMS DC PROGRAMMING

01/08/2004

Page 80/ 115

Alternate I/O PCB Specification

Figure 4-23 shows where you would add an alternate I/O PCB in your PL/I PROC OPTIONS MAIN pointer list, or your COBOL ENTRY USING statement. PL/I OLPGM: PROC (L_IO_PCB_PTR, Alternate I/O PCB Pointer L_DB1_PCB_PTR, Pointer L_DBn_PCB_PTR) Pointer OPTIONS (MAIN); COBOL ENTRY 'DLITCBL' USING L-IO-PCB, L-ALT-IOAlternate I/O PCB L-DB1-PCB, PCB L-DBn-PCB. I/O PCB Pointer L_ALT_IO_PCB_PTR, Data Base PCB

Data Base PCB

I/O PCB PCB, Data Base

Data Base PCB

Figure 4-23. Alternate I/O PCB Coding

Alternate PCB Mask

Like the I/O PCB, you need to code a PCB mask for the alternate PCB. The alternate PCB mask contains only three fields: the destination, the reserved IMS field and the status code. Figure 4-24 shows the typical code needed for an alternate PCB mask. PL/I DCL 01 L_ALT_IO_PCB 05 L_LTERM_TRAN 05 L_IMS_RSVD 05 L_STATUS_CODE COBOL LINKAGE SECTION. 01 L-ALT-IO-PCB. 05 L-LTERM-TRAN BASED(L_ALT_IO_PCB_PTR), CHAR(8), CHAR(2), CHAR(2);

PIC

X(8).

IMS DC PROGRAMMING

01/08/2004

Page 81/ 115

05 L-IMS-RSVD 05 L-STATUS-CODE

PIC PIC

X(2). X(2).

Figure 4-24. Alternate I/O PCB Mask

Change Call
To take advantage of a modifiable PCB, issue a DL/I change call. The change call has a function code of CHNG. Its function is to direct IMS to associate a particular LTERM or transaction code with a specific modifiable PCB. You issue the change call prior to issuing an ISRT call to the PCB. The CHNG will direct IMS, for all subsequent ISRT calls to that PCB, to send the message to the proper destination. An example of a CHNG call, followed by an ISRT call of an output message area (which will be displayed on a format for an alternate device such as a printer), is shown in Figure 4-25. The messages so inserted can be sent to the destination with the PURG call. The PURG call tells IMS that the message building is complete and the message may be sent onwards to the destination. You issue the PURG call before taking a sync point or issuing a GU against the I/O PCB. The destination needs to be set after every GU call to the I/O PCB as that implies a sync point for the application. The Alternate PCB(s) are defined ahead of other PCB(s) and therefore you need to take this into account when defining the linkage section (or using the PCB pointers in PL/I). Let's assume that the LTERM name for the printer is HAH23V, and that we want to use a particular report format, CT7ORPT1. PL/I W_DESTINATION = 'HAH23V': Set up LTERM destination CALL PLITDLI (C_PARM3, C_CHNG_FUNC, L_ALT_IO_PCB_PTR, W_DESTINATION); W_FMT_MODNAME = 'CT7ORPT1'; up format MOD name CALL PLITDLI (C_PARM4, C_ISRT_FUNC, L_ALT_IO_PCB_PTR, W_OUTPUT_MESSAGE, W_FMT_MODNAME); COBOL

Set

IMS DC PROGRAMMING

01/08/2004

Page 82/ 115

MOVE 'HAH23V ' TO WSet up LTERM destination CALL 'CBLTDLI' USING C-PARM3, C-CHNG-FUNC, L-ALT-IO-PCB, W-DESTINATION. MOVE 'CT7ORPT1 ' TO W-FMTSet up format MOD name CALL 'CBLTDLI' USING C-PARM4, C-ISRT-FUNC, L-ALT-IO-PCB, W-OUTPUT-MESSAGE, W-FMT-MODNAME.

DESTINATION.

MODNAME.

Figure 4-25. Change Call, with Insert, to Modifiable PCB (LTERM) Remember from the discussion of the ISRT call that you can only use the optional format parameter on the ISRT call for the first call. The application program must cause a commit point, or issue another CHNG call before it can ISRT with the format parameter specified. The specification of a transaction code in the PCB, via a CHNG call or hard coded PCB in the PSB, is known as a program-to-program message switch. This allows you to schedule IMS online programs from IMS online programs. Figure 4-26 shows the code necessary to perform a program-to-program message switch. Let's assume we want to schedule transaction 'CT7P1000' from a currently executing program. PL/I W_TRANCODE = 'CT7P1000': CALL PLITDLI (C_PARM3, C_CHNG_FUNC, L_ALT_IO_PCB_PTR, W_TRANCODE); W_ALT_OUTPUT_MSG_TRAN = insert Transaction code into the message CALL PLITDLI (C_PARM3, 'CT7P1000': set up Transaction code as destination

IMS DC PROGRAMMING

01/08/2004

Page 83/ 115

C_ISRT_FUNC, L_ALT_IO_PCB_PTR, W_ALT_OUTPUT_MSG); COBOL MOVE 'CT7P1000' TO W-TRANCODE. CALL 'CBLTDLI' USING C-PARM3 C-CHNG-FUNC L-ALT_IO-PCB W-TRANCODE. MOVE 'CT7P1000' TO W-ALT-OUTPUT-MSG-TRAN. the message CALL 'CBLTDLI' USING C-PARM3 C-ISRT_FUNC L-ALT-IO-PCB W-ALT-OUTPUT-MSG; Figure 4-26. Change Call, with Insert, to Modifiable PCB (Transaction) The ZZ byte of the message must be set to binary 0 or 1 prior to inserting the message. The LL will depend on the length of the message. If your PSB does not specify a modifiable PCB, it is not allowed to issue the CHNG call. When you issue a CHNG call, it will remain in effect until. Another CHNG call is issue to the same PCB. Your program terminates. A GU call to the message queue is issued.

set up Transaction code as destination

insert Trans code into

If the application program needs to send messages to multiple output destinations, it is recommended that it also issue the PURG call prior to the subsequent CHNG calls, so that IMS knows the message is complete and will send the message to its destination. The only acceptable status code from the CHNG call is blanks. If an A1 status is returned to the application program, it means that the LTERM or transaction code is not defined to IMS.

IMS DC PROGRAMMING

01/08/2004

Page 84/ 115

IMS DC PROGRAMMING

01/08/2004

Page 85/ 115

Conversational Applications
Conversational applications are those applications that have to save data (context) between terminal interactions. There are three ways of doing this:1. Write it to a terminal screen field that has the PROT, NODISP and MDT on. However there are two drawbacks to this approach. One is that the amount of data saved has to be small. Another is that a user can always press the clear key and erase the terminal buffer. This approach is useful if the data is small and it does not matter much to start all over again if the data is lost. 2. Another way is to write the data to a database. This approach while imposing no restrictions on the amount of data or its safety, does have the drawback that a data base has to be defined exclusively for this, along with associated necessary programming efforts. 3. The third approach is to use an IMS facility called a SPA or a scratch pad area. For IMS to supply this area, the transaction has to be defined as conversational. Every terminal that initiates this program is provided its own scratch pad area. When the output message is saved, the SPA is saved too. When the next message is retrieved, so is the SPA. This allows a single copy of a conversational program to work with more than one terminal. You can think of a SPA as another type of message. However in addition to the LL and ZZ prefixes, it has another half word prefix CI. The CI field is maintained by IMS although you need to provide for it in your application, just like the LL and ZZ fields. DCL 01 SPA_IO_AREA, 2 SPA_LL FIXED_BINARY(31), 2 SPA_ZZ FIXED_BINARY(15), 2 SPA_CI FIXED_BINARY(15), 2 SPA_TRANSACTION_CODE CHAR(8), 2 SPA_USER_DATA CHAR(nn); Note that for conversational programs the transaction code does not appear in the first message of a conversational program The first GU call that a conversational program makes against the I/O PCB in a conversation, fetches a new SPA with the transaction code set. You get the input message by issuing a GN against the I/O PCB after the preceding GU for the SPA. You save the SPA using an ISRT call against the I/O PCB, before you ISRT the output message. You must not change the transaction code in the SPA while the conversation is in

IMS DC PROGRAMMING

01/08/2004

Page 86/ 115

progress. You set this field to spaces when you issue the last ISRT for the SPA to tell IMS that the conversation is ending. Another point to note for conversational transactions is that it is better to make all data base changes in the last iteration. If you do them in earlier iterations, the changes are committed while issuing a GU against the I/O PCB for the next input message. This may lead to inconsistent updates if the program abends later in the conversation. To fetch the SPA, CALL PLITDLI ( C-3, C_GU, IO_PCB_PTR, SPA_IO_AREA); To save the SPA, CALL PLITDLI ( C-3, C_ISRT, IO_PCB_PTR, SPA_IO_AREA);

Passing the Conversation to another Conversational Program

A conversational program can pass the conversation to another conversational program in two ways:

A deferred switch.
The program can respond to the terminal but cause the next input from the terminal to go to another conversational program by: 1. Issuing an ISRT call against the I/O PCB to respond to the terminal 2. Placing the transaction code for the new conversational program in the SPA 3. Issuing an ISRT call referencing the I/O PCB and the SPA to return the SPA to IMS TM IMS TM then routes the next input message from the terminal to the program associated with the transaction code that was specified in the SPA. Other conversational programs can continue to make program switches by changing the transaction code in the SPA.

IMS DC PROGRAMMING

01/08/2004

Page 87/ 115

An immediate switch.
The program can pass the conversation directly to another conversational program by issuing an ISRT call against the alternate PCB that has its destination set to the other conversational program. The first ISRT call must send the SPA to the other program, but the program passing control can issue subsequent ISRT calls to send a message to the new program. If the program does this, in addition to routing the SPA to the other conversational program, IMS TM updates the SPA as if the program had returned the SPA to IMS. If the program does an immediate switch, the program cannot also return the SPA to IMS TM or respond to the original terminal.

IMS DC PROGRAMMING

01/08/2004

Page 88/ 115

BTS (Batch Terminal Simulator )

back

One of the more popular tools used to test IMS online application programs is the IBM Batch Terminal Simulator II. This product offers many advantages to the systems engineer that otherwise would not be available in the IMS online environment. These advantages include the following: The ability to test an online program before the actual IMS system generation has been done for the transaction (PSB, DBD, data base Dynamic Allocation Table, and hardware). Testing can also be done before the Application Control Block (ACB) has been generated. The ability to dynamically trace all message queue and data base calls, as well as display their I/O areas, PCB masks, and SSAS. The ability to see the actual MFS screen layout, as well as the message I/O area.

BTS II can, and should, be used to also test IMS batch and BMP application programs. Let's take a closer look at the three major advantages of using BTS II to see why they are beneficial. 1. Before you can run anything in the IMS online environment, you must define all hardware, software, data you intend to use. The hardware includes display terminals and printers. Some of the things that need to be defined are the device type, model, and what type of communication link exists, such as BISYNC or SDLC. The software includes your transaction name and its associated PSB. In the online environment, your application program name and PSB name must be the same. The data includes all DBDS, DD names, and data base data sets. You must also have an ACB control block created for all your PSBS and DBDS, because the IMS online system does not dynamically build ACBS from the PSB and DBD libraries. As you can see, it takes planning to implement IMS online applications. Furthermore, most IPCS only perform the IMS online system generation once or twice a month. (Could you imagine having to wait a month before you could test a program?) BTS II allows us to simulate that environment before it actually exists, so the testing and implementation of IMS applications can be timely. 2. The second advantage is that through the use of BTS II control statements (which will be discussed later), you can display the contents of all message and data base I/O

IMS DC PROGRAMMING

01/08/2004

Page 89/ 115

areas. PCB masks, SSAS, scratch pad areas and program statistics can also be displayed. Having all this information available to you on a call-by-call basis is tremendously helpful in a debugging situation. It speeds up the debugging phase of coding, as well as the implementation phase. Another feature is that all these output options can be turned on or off, depending on your needs. 3. The third advantage is the ability to see how MFS displays will look to the client when actually run in the online environment. As we will see later, the TSO foreground implementation of BTS II will present you with the display exactly as it will look, including the attributes assigned to each field. This is a very effective method of prototyping a system to your client prior to the online system generation. If the foreground TSO implementation of BTS II is not available to you, the batch version will draw a picture of the display, as well as indicate attribute values and cursor position. Although the batch version is not as effective in presenting screen displays, it is very effective in providing you with a hard copy of your program calls and I/O area contents. This is the version that we will be using for hands on in this class.

BTS II Batch
The BTS II batch execution is used most often to obtain a hard copy of the I/O areas and call sequence that an IMS application program makes. It is accomplished by submitting a batch job and using BTS II control statements as input. See the section on Project work for sample procedures and JCL. An illustrative sample is shown below. //JS010 EXEC PGM=BTSRC000, // PARM='DLI,007,0000,,O..N,O,T'.REGION=1500K //STEPLIB DD DSN=IMSVST1.RESLIB,DISP=SHR // DD DSN=IMSVST1.PGMLIB,DISP=SHR //IMS DD DSN=IMSVST1.DBDLIB,DISP=SHR // DD DSN=IMSVST1.PSBLIB.DISP=SHR //DFSRESLB DD DSN=IMSVST1.RESLIB.DISP=SHR //IEFRDER DD DUMMY //SYSPRINT DD SYSOUT=$ //SYSOUT DD SYSOUT=$ //DFSVSAMP DD DSN=IMSVST1.VSAMBUFF.DISP=SHR //database DD DSN=*** your test data base *** //FORMAT DD DSN=IMSVST1.TFORMAT.DISP=SHR //OIOPCB DD UINIT=SYSDA,SPACE=(CYL.(1,1),RLSE). // DCB=(LRECL=512,BLKSIZE=3072) //QALTPCB DD UNIT=SYSDA,SPACE=(CYL.(1,1),RLSE), // DCB=(LRECL=512,BLKSIZE=3072) //QALTRAN DD UNIT=SYSDA,SPACE=(CYL,(1,1),RLSE). // DCB=BLKSIZE=532 //BTSOUT DD SYSOUT=$,DCB=(RECFM=LRECL=133,BLKSIZE=1330) //BTSIN DD DSN=CTDS???.IMSCLASS.LIB (BTSIN),DISP=SHR

IMS DC PROGRAMMING

01/08/2004

Page 90/ 115

Figure BTS II Batch JCL The EXEC card, DD names, and their purposes are described below: JS010 This is the EXECUTE card. Program BTSRC000 is the batch BTS II application program. Check with your installation as to the value of the parameters supplied to BTS II. Refer to the IBM manual Batch Terminal Simulator II Program Description/Operations Manual- as to the meaning of each parameter. The only parameter that you are likely to change is the first one. The figure above shows DLI as the value. This will be the normal value used; DBB and BMP are also valid. In the case of DBB and BMP, you will need to add DD name 'IMSACB' and point it to the ACB library where your ACBS reside. STEPLIB This should point to (concatenated if need be) the libraries where not only BTSRC000 resides, but all the IMS application programs you intend to execute with this batch job. IMS This DD points to the PSB and DBD libraries. It must be a concatenation of the two, but the order does not matter. DFSRESLB This DD points to the library containing the IMS modules. IEFRDER This is the IMS log file DD statement. This log facility is only simulation and the log file itself is not valid for database back out utilities. Because this file is usually dummied out, it is highly recommended that you use test databases for testing purposes. DFSVSAMP This DD refers to the IMS data base VSAM buffer specifications. database Here you will include all DD names required for the IMS databases needed to support the IMS application programs you are executing. FORMAT This DD statement points to the MFS format library where your format control blocks are stored. QIOPCB This DD statement is a BTS II work dataset containing the output message queue to the 3270 screen and printer. QALTPCB

IMS DC PROGRAMMING

01/08/2004

Page 91/ 115

This DD points to the work dataset containing the message queue for alternate PCBs to 3270 screens and printers. QALTRAN This DD is for a BTS II work dataset. BTSOUT This is the DD statement where all the BTS II output is produced. BTSIN This DD statement is where the BTS II control cards are input. They can be in line with BTSIN DD * , or a dataset. Note: Look at the section Project for the JCL to run BTS.

IMS DC PROGRAMMING

01/08/2004

Page 92/ 115

Control Statements
Several control statements are available in BTS II, but only a few are used regularly. Figure below shows a table of common control statements and associated keywords, if any, and some common BTS II command statements. Use the ./T command to define Transactions to BTS ./T TC=trans-code specify DUMMY for Batch MBR=program LANG=CBL | PLI TYPE=MSG | BMP | DLI [ PSB=psb-name ] needed only if psb name is other than program name [ SPA=spa-size ] [ PLC=limit-count ]

TC This keyword specifies the online transaction name or LTERM name. For batch jobs, the name DUMMY is normally used because no transaction name is associated with batch jobs. MBR This is the load module name that your application program was linked under.. PSB This is the PSB name that is to be used with your application program. LANG This is the programming language in which your application program was written, specified by MBR= . Valid values are ASM for IBM 370 Assembler Language, CBL for COBOL, and PLI for PL/I. TYPE This indicates the type of application program to be executed. Valid values are: 'DLI' for batch programs, MSG for online programs and BMP for BMP programs. PLC This is the Process Limit Count. The number can be from 0 to 65535, and is used by BTS-II to determine when a QC status code (no more input messages) will be returned for a GU call to the message queue. In the case of a printer, or other alternate device, the value is zero.

IMS DC PROGRAMMING

01/08/2004

Page 93/ 115

You can also use the ./T command to specify a terminal as an alternate destination. For example if you want to send a message to a terminal that is an alternate destination you should define it like this ./T TC=terminal TYPE=3270-An SIZE=(LL,CC) [ FEAT= ]

Use the ./O command to specify what information BTS should provide for you. ./O [ APS=YES | NO ] [ DB=YES | NO ] [ MSG=YES | NO ] [ SCREEN=INOUT | OUT | NO ] [ ATR=YES | NO ] [ EATR=YES | NO ] [ SPA=YES | NO ]

APS Yes indicates that statistics about calls made by the application should be printed. DB Yes indicates that DB calls should be traced MSG Yes indicates that MSG calls should be traced SCREEN INOUT specifies both input and output screens should be printed ATR Yes specifies that attribute bytes on the screens should be printed EATR Yes specifies that extended attribute bytes should be printed. SPA Yes specifies that contents of SPA are to be traced and printed. Use the ./D command to define terminals to BTS ./D TYPE=3270-An SIZE=(LL,CC) [ FEAT=hh ] [ EOM=eom-char ]

Use the ./* to indicate a comment line to document your script

IMS DC PROGRAMMING

01/08/2004

Page 94/ 115

Other inputs that can be given via BTSIN /FOR modname PFKnn PAn LnnCnn xxx ENTER CLEAR Trancode $ /FOR modname This statement is used to invoke an MFS format specified by modname. PFKnn This statement invokes the function defined for the PFKEY. This is the function defined in your MFS format. The value specified by nn can range from 1 to 24. PF12 is simulated by BTS II as the IMS screen copy facility. Note: For PF keys 1 through 9, you must not use a leading zero. PFK01 will not work; PFK1 will. Each PFKnn must appear on a separate line. No other commands may be on that line, except for the $. PAn This statement invokes the Program Access key specified by n. PA1 is for logical paging, and PA2 retrieves the next message in the message queue. Each PAn must appear on a separate line. No other commands may be on that line, except for the $. LnnCnn 'xxx' This statement allows for the input of data onto an MFS screen. The data represented by 'xxx' is entered onto the line specified by Lnn and columns specified by Cnn. The data must be enclosed by single quotes. The input data can span more than one line. Indicate continuation lines by coding a non blank character in column 72. ENTER This statement causes BTS II to act as if the ENTER key was pressed on the keyboard. tranncode This invokes a transaction specified by trancode. In the case of a batch job using TC=DUMMY, you must specify DUMMY for trancode to force the batch job to execute. Each trancode command must appear on a separate line. No other commands may be on that line, except for the $

IMS DC PROGRAMMING

01/08/2004

Page 95/ 115

$ (batch This statement terminates the input to BTS II and causes BTS II to end ) Shown on the next page are sample BTSIN input cards. ***** CONTROL STATEMENTS TO EXECUTE A BATCH PROGRAM ***** ./T TC=DUMMY MBR=CT7P01S1 PSB=CT7BOPPS LANG=PLI TYPE =DLI DUMMY $ ***** CONTROL STATEMENTS TO EXECUTE AN ONLINE PRGRAM***** ./D TYPE=3270-A2 SIZE=(24,80) ./T TC=CT7PED01 MBR=CT7PED01 PSB=CT7PED01 LANG=PLI TYPE=MSG /FOR CT7001M2 PFK1 L09C45 '100004' ENTER L09C45 '100005' ENTER $

IMS DC PROGRAMMING

01/08/2004

Page 96/ 115

IMS Commands

back

As you are testing your application program, you may need to issue IMS operator commands that provide services to you, as well as provide important information. A certain subset of IMS operator commands are useful in the test environment, and are described below. You can always use the long form of the command. (The slash, followed by the first three characters of the command, is a valid short form.) Examples would be/TES (short for/TEST) and /FOR (short for /FORMAT). Figure 3-4 shows a table of common IMS Test System commands.

Command /TEST /FORMAT /DISPLAY

/START /STOP /DBRECOVERY /RSTART /END /RCLSDST

Example /TEST MFS or /TEST MFS NODE LTERM /TES MFS or /TES MFS NODE LTERM /FORMAT modname or /FOR modname /DISPLAY TRANSACTION trancode. or /DIS PROGRAM progname,.. or /DIS DATABASE ddname, or /DIS NOTE LTERM, /START TRAN trancode,. or /STA PROG progname,. or /STA DB ddname, /STOP TRAN trancode, or /STO PROG progname, or /STO DB ddname,. /DBRECOVERY ddname,.. NOFEOV or /DBR ddname,.. NOFEOV /RSTART NODE LTERM1 LTERM2 or /RST NODE LTERM1 LTERM2 or /END or /END NODE LTERM /RCLSDST or /RCL

Figure 3-4. Common IMS Test System Commands

The first two commands,/TEST and /FORMAT, should always be available for your use. Others may not be. The following list explains the common commands in detail. /TEST

IMS DC PROGRAMMING

01/08/2004

Page 97/ 115

This command is used to put IMS in the MFS test mode. In the test IMS system, you are allowed to regenerate MFS formats and test them right away, a facility not available in the production IMS system. To take advantage of this test facility, you must issue the following test command the first time you enter the IMS test system: /TEST MFS or /TES MFS This will put IMS into the MFS test mode. You will now be able to retrieve MFS formats from the test format library. If you wish to test alternate devices, like 3270 printers, you must issue a variation of /TEST in addition to the /TEST MFS command. The command looks like the following: /TEST MFS NODE LTERM or /TES MFS NODE LTERM The NODE keyword is where you specify the device ID that is known to IMS. For example, if you wanted to test an application that writes MFS messages to a 3287 printer, and the printer ID is HAH23V, the command is /TEST MFS NODE HAH23V /FORMAT This command is used to retrieve MFS MODs from the test MFS library. The command used to retrieve MOD CT7001M1 would be /FORMAT CT7001M1 or /FOR CT7001M1 /DISPLAY This command displays the information requested in the command. There are several pieces of information that can be displayed. Below are examples of the display command: /DISPLAY TRANSACTION CT7P01S1.... /DIS PROGRAM CT7P01S1.... /DIS DATABASE CT7DPDA1..... /DIS NODE WRDT0333..... display transaction info display program info display data base info display node info

The above examples give only a small sample of the type of information that can be displayed. /START This command starts the various IMS resources that have been stopped either by the operator or by program abend. Examples are the following: /START TRANSACTION CT7P01S1 (start the stopped transactions) /STA PROGRAM CT7P01S1 (start the stopped programs) /STA DATABASE CT7DPDA1 (start the stopped data bases)

IMS DC PROGRAMMING

01/08/2004

Page 98/ 115

/STOP This command stops the various IMS resources that are active. Some examples include the following: /STOP TRANSACTION CT7P01S1 /STO PROGRAM CT7P01S1 /STO DATABASE CT7DPDA1 (stop the active transactions) (stop the active programs) (stop the active data bases)

/DBRECOVERY This command stops and deallocates IMS databases from IMS online. It also stops the scheduling of any transactions or programs that use the databases using DBR. A true recovery is not always done. This command should only be issued when it is necessary to perform maintenance to the database. The NOFEOV keyword should also be used so that a log file switch is not made by IMS. AN example is: /DBRECOVERY CT7DPDA1 or /DBR CT7DPDA1..... NOFEOV /RSTART This command starts an IMS node after it has been stopped by a previous transaction abend, or stopped by issuing a /STOP command. An example is: /RSTART NODE WRDT0333 or /RST NODE WRDT0333 /END This command terminates the test mode invoked by the /TEST command, specifically the TEST MFS mode. An example is: /END If you have been testing alternate devices, like 3270 printers, you must issue a variation to the /END command. The command to terminate the test mode of alternate devices looks like the following: /END NODE LTERM The NODE keyword is where you specify the device ID known to IMS. For example, if you have been testing an application that writes MFS messages to a 3287 printer and the printer ID is HAH23V, the command you would issue to terminate the device test is /END NODE HAH23V

IMS DC PROGRAMMING

01/08/2004

Page 99/ 115

The /END command and the /END NODE command, like the /TEST MFS and /TEST NODE commands, are not mutually exclusive, but are both required to terminate a test session if both /TEST commands were issued to start the session. /RCLSDST This command logs you off and disconnects your device from IMS. This command stands for Remote CLose DeSTination. An example is /RCLSDST or /RCL Note: More detailed information on the various operator commands can be found in IMS/VS Operator's Reference Manual.

IMS DC PROGRAMMING

01/08/2004

Page 100/ 115

Project Work

back

Before you try out your first IMS/DC program using the BTS simulator, you must have a test database. In this course you will use the Patient Data Base that was illustrated in the IMS DB class. You will then write IMS/DC application program(s) to try out this database. The program will use MFS to capture user input and will display output data using MFS. To start you off, the following artifacts are provided:1. DBD for the database using HISAM (PNTDBHIS) 2. PSB for loading the database (PNTPHISL) 3. PSB for reading from the database (PNTPHISG) 4. A load program written in COBOL (LOADPGM) 5. A Read program written in COBOL suitable for BATCH (READPGM) 6. A MFS Format set that can accept a PATNO and output PATIENT details (TEST1). 7. An IMS DC program that reads a PATNO from the screen and outputs the PATIENT segment (READPGMO). 8. Test Data to Load the database. The following Program preparation artifacts are provided but need customization. The lines that need customization are colored blue. 1. A DBDGEN procedure 2. A PSBGEN procedure 3. A COBOL compile and link procedure customized for COBOL / IMS (IGYWCL) 4. A MFSUTL procedure for preparing your message format sets (MFSUTL). 5. A DLIBATCH procedure for running your LOAD and READ programs in batch (DLIBATCH) 6. A BTS procedure (BTS) 7. DBD preparation JCL (DBD) 8. PSB preparation JCL (PSB) 9. JCL to define your VSAM clusters for the sample database

IMS DC PROGRAMMING

01/08/2004

Page 101/ 115

10. COBOL preparation JCL (COBCL) 11. MFS preparation JCL (MFS) 12. JCL to run your Batch IMS program. Use it to load your database and test whether it has been loaded properly. (IMSRUN) 13. JCL to run a Batch Program under BTS (BTSRUNB) 14. JCL to run a DC Program under BTS (BTSRUNO)

The hierarchic structure of the database is given below:+----------+ PATIENT +----------+ +----------------+----------------+ +----------+ +----------+ +-----------+ ILLNESS BILLING HOUSHOLD +----------+ +----------+ +-----------+ +----------+ +----------+ TREATMNT PAYMENT +----------+ +----------+

PATIENT SEGMENT, PATIENT has a unique key field: PATNO. PATIENT segments are stored in ascending order of their patient numbers.
+----------------------------+ PATNO NAME ADDR +--------+----------+-------- 5 10 30 +----------------------------+

ILLNESS SEGMENT, The key field is ILLDATE. Because it is possible for a patient to come to the clinic with more than one illness on the same date, this key field is not unique; For segments with equal keys or no keys, the RULES keyword determines where the segment is inserted. Where RULES=LAST, ILLNESS segments that have an equal key are stored on a first-in first-out basis among those with equal keys. ILLNESS segments with unique keys are stored in ascending order on the date field, regardless of RULES. ILLDATE is specified in the format YYYYMMDD.
+---------------------+ ILLDATE ILLNAME +---------+----------- 8 10 +---------------------+

IMS DC PROGRAMMING

01/08/2004

Page 102/ 115

TREATMNT SEGMENT, The key field of the TREATMNT segment is DATE. Because a patient may receive more than one treatment on the same date, DATE is a non unique key field. TREATMNT, like ILLNESS, has been specified as having RULES=LAST. TREATMNT segments with equal date keys are also stored on a first-in-first-out basis. DATE is specified in the same format as ILLDATE--YYYYMMDD.
+---------------------------------------+ DATE MEDICINE QUANTITY DOCTOR +------+-----------+----------+--------- 8 10 4 10 +---------------------------------------+

BILLING SEGMENT, BILLING has no key field.

+----------+ BILLING +---------- 6 +----------+

PAYMENT SEGMENT, the PAYMENT segment has no key field.

+-----------+ PAYMENT +----------- 6 +-----------+

HOUSHOLD SEGMENT, RELNAME is the key field.

+-----------------+ RELNAME RELATN +--------+-------- 10 8 +-----------------+

Create the following datasets before you begin the setup * USERID.DBD.SOURCE FB PDS 80/800 * USERID.PSB.SOURCE FB PDS 80/800 * USERID.COBOL.SOURCE FB PDS 80/800 * USERID.JCL FB PDS 80/800 * USERID.PROCLIB FB PDS 80/800 * USERID.MFS.SOURCE FB PDS 80/800 * USERID.LOAD.DATA FB PDS 80/800 * USERID.REFERAL FB PDS 80/10720 * USERID.LOADLIB U PDS /32760 * USERID.DBDLIB U PDS /32760

IMS DC PROGRAMMING

01/08/2004

Page 103/ 115

* USERID.PSBLIB * USERID.TFORMAT PNTDBHIS DBD

PDS U

/32760 PDS /23200

DBD NAME=PNTDBHIS,ACCESS=HISAM DATASET DD1=PNTDBHIS,OVFLW=PNTOVFLW SEGM NAME=PATIENT,BYTES=45,PARENT=0 FIELD NAME=(PATNO,SEQ,U),BYTES=5,START=1,TYPE=C FIELD NAME=NAME,BYTES=10,START=6,TYPE=C FIELD NAME=ADDR,BYTES=30,START=16,TYPE=C SEGM NAME=ILLNESS,BYTES=18,PARENT=PATIENT FIELD NAME=(ILLDATE,SEQ,M),BYTES=8,START=1,TYPE=C FIELD NAME=ILLNAME,BYTES=10,START=9,TYPE=C SEGM NAME=TREATMNT,BYTES=32,PARENT=ILLNESS FIELD NAME=(DATE,SEQ,M),BYTES=8,START=1,TYPE=C FIELD NAME=MEDICINE,BYTES=10,START=9,TYPE=C FIELD NAME=QUANTITY,BYTES=4,START=19,TYPE=C FIELD NAME=DOCTOR,BYTES=10,START=23,TYPE=C SEGM NAME=BILLING,BYTES=6,PARENT=PATIENT FIELD NAME=BILLING,BYTES=6,START=1,TYPE=C SEGM NAME=PAYMENT,BYTES=6,PARENT=BILLING FIELD NAME=PAYMENT,BYTES=6,START=1,TYPE=C SEGM NAME=HOUSHLD,BYTES=18,PARENT=PATIENT FIELD NAME=RELNAME,BYTES=10,START=1,TYPE=C FIELD NAME=RELATN,BYTES=8,START=11,TYPE=C DBDGEN FINISH END

PNTPHISL Load PSB

PCB TYPE=DB,NAME=PNTDBHIS,PROCOPT=LS,KEYLEN=21 SENSEG NAME=PATIENT,PARENT=0 SENSEG NAME=ILLNESS,PARENT=PATIENT SENSEG NAME=TREATMNT,PARENT=ILLNESS SENSEG NAME=BILLING,PARENT=PATIENT SENSEG NAME=PAYMENT,PARENT=BILLING SENSEG NAME=HOUSHLD,PARENT=PATIENT PSBGEN PSBNAME=PNTPHISL,LANG=COBOL END

PNTPHISG Add, Get, Replace, Delete PSB

PCB TYPE=DB,NAME=PNTDBHIS,PROCOPT=A,KEYLEN=21 SENSEG NAME=PATIENT,PARENT=0 SENSEG NAME=ILLNESS,PARENT=PATIENT SENSEG NAME=TREATMNT,PARENT=ILLNESS SENSEG NAME=BILLING,PARENT=PATIENT SENSEG NAME=PAYMENT,PARENT=BILLING SENSEG NAME=HOUSHLD,PARENT=PATIENT PSBGEN PSBNAME=PNTPHISG,LANG=COBOL END

IMS DC PROGRAMMING

01/08/2004

Page 104/ 115

LOADPGM
IDENTIFICATION DIVISION. PROGRAM-ID. LOADPGM. ****************************************************************** * E N V I R O N M E N T D I V I S I O N * ****************************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT INFILE ASSIGN TO INFILE ORGANIZATION IS SEQUENTIAL ACCESS IS SEQUENTIAL FILE STATUS IS FILE-STAT. ****************************************************************** * D A T A D I V I S I O N * ****************************************************************** DATA DIVISION. FILE SECTION. FD INFILE RECORD CONTAINS 80 CHARACTERS. 01 IN-REC PIC X(80). ****************************************************************** * W O R K I N G S T O R A G E * ****************************************************************** WORKING-STORAGE SECTION. 01 WORK-AREAS. 05 PARM-COUNT PIC S9(09) COMP VALUE 3. 05 FUNCN PIC X(4) VALUE 'ISRT'. 05 FILE-STAT PIC X(2) VALUE ' '. 01 IO-BUFFER. 05 SSA PIC X(10). 05 SEG-IO-AREA PIC X(70). 01 SWITCHES. 05 S-FLAG-BIT PIC X(01) VALUE LOW-VALUES. 88 S-FLAG VALUE HIGH-VALUES. LINKAGE SECTION. 01 PCBMASK. 05 DBD-NAME PIC X(08). 05 SEG-ID PIC X(02). 05 STATS PIC X(02). 05 PROCOPT PIC X(04). 05 FILLER PIC X(04). 05 SEGMENT-NAME PIC X(08). 05 LENGTH-FDBK PIC S9(05) COMP. 05 NUMBER-SENSEGS PIC S9(05) COMP. 05 KEY-FDBK-AREA PIC X(21). ****************************************************************** * PROCEDURE DIVISION * ****************************************************************** PROCEDURE DIVISION. ENTRY 'DLITCBL' USING PCBMASK PERFORM MAIN-PARA PERFORM FINAL-PARA.

IMS DC PROGRAMMING

01/08/2004

Page 105/ 115

MAIN-PARA. OPEN INPUT INFILE PERFORM UNTIL S-FLAG READ INFILE RECORD INTO IO-BUFFER AT END MOVE HIGH-VALUES TO S-FLAG-BIT END-READ IF NOT S-FLAG CALL 'CBLTDLI' USING FUNCN, PCBMASK, SEG-IO-AREA, SSA DISPLAY SEG-IO-AREA END-IF END-PERFORM. FINAL-PARA. DISPLAY 'END OF PROGRAM' GOBACK. A100-EXIT. EXIT.

READPGM
IDENTIFICATION DIVISION. PROGRAM-ID. READPGM. ****************************************************************** * E N V I R O N M E N T D I V I S I O N * ****************************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. INPUT-OUTPUT SECTION. FILE-CONTROL. ****************************************************************** * D A T A D I V I S I O N * ****************************************************************** DATA DIVISION. FILE SECTION. ****************************************************************** * W O R K I N G S T O R A G E * ****************************************************************** WORKING-STORAGE SECTION. 01 WORK-AREAS. 05 PARM-COUNT PIC S9(09) COMP VALUE 3. 05 FUNCN PIC X(4) VALUE 'GN '. 05 SEG-IO-AREA PIC X(45). 05 SSA PIC X(09) VALUE 'PATIENT'. 01 CONSTANTS. 05 C-GB PIC X(2) VALUE 'GB'. 01 SWITCHES. 05 S-FLAG-BIT PIC X(01) VALUE LOW-VALUES. 88 S-FLAG VALUE HIGH-VALUES. LINKAGE SECTION. 01 PCBMASK. 05 DBD-NAME PIC X(08). 05 SEG-ID PIC X(02). 05 STATS PIC X(02). 05 PROCOPT PIC X(04). 05 FILLER PIC X(04).

IMS DC PROGRAMMING

01/08/2004

Page 106/ 115

05 SEGMENT-NAME PIC X(08). 05 LENGTH-FDBK PIC S9(05) COMP. 05 NUMBER-SENSEGS PIC S9(05) COMP. 05 KEY-FDBK-AREA PIC X(21). ****************************************************************** * PROCEDURE DIVISION * ****************************************************************** PROCEDURE DIVISION. ENTRY 'DLITCBL' USING PCBMASK PERFORM MAIN-PARA PERFORM FINAL-PARA. MAIN-PARA. CALL 'CBLTDLI' USING FUNCN, PCBMASK, SEG-IO-AREA. DISPLAY 'SEGMENT NAME ' SEGMENT-NAME DISPLAY 'SEGMENT AREA ' SEG-IO-AREA PERFORM UNTIL S-FLAG MOVE SPACES TO SEG-IO-AREA CALL 'CBLTDLI' USING FUNCN, PCBMASK, SEG-IO-AREA IF STATS NOT = C-GB DISPLAY 'SEGMENT NAME ' SEGMENT-NAME DISPLAY 'SEGMENT AREA ' SEG-IO-AREA END-IF IF STATS = C-GB DISPLAY 'NON BLANK FROM GN CALL ' STATS MOVE HIGH-VALUES TO S-FLAG-BIT END-IF END-PERFORM. FINAL-PARA. DISPLAY 'END OF PROGRAM' GOBACK. A100-EXIT. EXIT.

IMS DC PROGRAMMING

01/08/2004

Page 107/ 115

TEST1 MFS
TEST1F

SYSDATE SYSTIME PATNO

NAME ADDRESS IOSTAT DBSTAT TEST1I

TEST1O

PRINT NOGEN FMT DEV TYPE=3270-A2,FEAT=IGNORE,PFK=(PFKEYSOO, X 3='/FOR TEST1O') DIV TYPE=INOUT DPAGE CURSOR=((06,25)),FILL=PT DFLD 'TEST1F',POS=(01,2),ATTR=(NUM,PROT,HI) DFLD 'PATIENT INQUIRY PROGRAM',POS=(01,26), X ATTR=(ALPHA,PROT,HI) DFLD 'READPGMO',POS=(01,56),ATTR=(ALPHA,PROT,HI) DFLD 'DATE:',POS=(02,2),ATTR=(ALPHA,PROT,HI) DFLD POS=(02,8),LTH=8,ATTR=(ALPHA,PROT,NORM) DFLD 'TIME:',POS=(02,56),ATTR=(ALPHA,PROT,HI) DFLD POS=(02,62),LTH=08,ATTR=(ALPHA,PROT,NORM) DFLD 'PATIENT NUMBER:',POS=(06,02),ATTR=(ALPHA,PROT,HI) DFLD POS=(06,25),LTH=05,ATTR=(NUM,NOPROT,NORM,MOD) DFLD '(PF3 - RETURN TO MENU)',POS=(09,02), X ATTR=(ALPHA,PROT,HI) DFLD '=======================================================X ==',POS=(10,2),ATTR=(ALPHA,PROT,HI) DFLD 'PATIENT NAME :',POS=(11,02), X ATTR=(ALPHA,PROT,HI) DFLD POS=(11,25),LTH=10,ATTR=(ALPHA,PROT,NORM) DFLD 'PATIENT ADDRESS :',POS=(13,02), X ATTR=(ALPHA,PROT,HI) DFLD POS=(13,25),LTH=30,ATTR=(ALPHA,PROT,NORM) DFLD 'IO-STAT :',POS=(14,02), X ATTR=(ALPHA,PROT,HI) DFLD POS=(14,25),LTH=2,ATTR=(ALPHA,PROT,NORM) DFLD 'DB-STAT :',POS=(15,02), X ATTR=(ALPHA,PROT,HI) DFLD POS=(15,25),LTH=2,ATTR=(ALPHA,PROT,NORM) FMTEND MSG TYPE=INPUT,SOR=(TEST1F,IGNORE),OPT=1,NXT=TEST1O SEG MFLD (PFKEYSOO,'READPGMO '),LTH=14,JUST=L,ATTR=NO MFLD PATNO,LTH=05,JUST=R,ATTR=NO,FILL=C'0' MSGEND MSG TYPE=OUTPUT,SOR=(TEST1F,IGNORE),OPT=1,PAGE=NO, X NXT=TEST1I SEG MFLD (SYSDATE,DATE2) MFLD (SYSTIME,TIME) MFLD PATNO,LTH=05,JUST=R MFLD NAME,LTH=10,JUST=L MFLD ADDRESS,LTH=30,JUST=L MFLD IOSTAT,LTH=2,JUST=L MFLD DBSTAT,LTH=2,JUST=L MSGEND END

IMS DC PROGRAMMING

01/08/2004

Page 108/ 115

READPGMO

IDENTIFICATION DIVISION. PROGRAM-ID. READPGMO. ****************************************************************** * E N V I R O N M E N T D I V I S I O N * ****************************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. INPUT-OUTPUT SECTION. FILE-CONTROL. ****************************************************************** * D A T A D I V I S I O N * ****************************************************************** DATA DIVISION. FILE SECTION. ****************************************************************** * W O R K I N G S T O R A G E * ****************************************************************** WORKING-STORAGE SECTION. 01 WORK-AREAS. 05 PARM-COUNT PIC S9(09) COMP VALUE 3. 05 C-GU PIC X(4) VALUE 'GU '. 05 C-ISRT PIC X(4) VALUE 'ISRT'. 01 SEG-IO-AREA. 05 DB-PATNO PIC X(5). 05 DB-NAME PIC X(10). 05 DB-ADDRESS PIC X(30). 01 SSA-Q. 05 FILLER PIC X(08) VALUE 'PATIENT'. 05 FILLER PIC X VALUE '('. 05 FILLER PIC X(8) VALUE 'PATNO'. 05 FILLER PIC X(2) VALUE ' ='. 05 SSA-ARG PIC X(5). 05 FILLER PIC X VALUE ')'. 01 IO-IN-AREA. 05 IN-LL PIC S9(4) COMP. 05 IN-ZZ PIC S9(4) COMP. 05 IN-TRANCODE PIC X(14). 05 IN-PATNO PIC X(5). 01 IO-OUT-AREA. 05 OUT-LL PIC S9(4) COMP VALUE 53. 05 OUT-ZZ PIC S9(4) COMP VALUE 0. 05 OUT-PATNO PIC X(5). 05 OUT-NAME PIC X(10). 05 OUT-ADDRESS PIC X(30). 05 OUT-IO-STAT PIC X(2). 05 OUT-DB-STAT PIC X(2). LINKAGE SECTION. 01 IO-PCB. 05 FILLER PIC X(10). 05 IO-STAT PIC X(02). 01 PCBMASK. 05 DBD-NAME PIC X(08). 05 SEG-ID PIC X(02). 05 DB-STAT PIC X(02).

IMS DC PROGRAMMING

01/08/2004

Page 109/ 115

05 PROCOPT PIC X(04). 05 FILLER PIC X(04). 05 SEGMENT-NAME PIC X(08). 05 LENGTH-FDBK PIC S9(05) COMP. 05 NUMBER-SENSEGS PIC S9(05) COMP. 05 KEY-FDBK-AREA PIC X(21). ****************************************************************** * PROCEDURE DIVISION * ****************************************************************** PROCEDURE DIVISION. ENTRY 'DLITCBL' USING IO-PCB PCBMASK PERFORM MAIN-PARA PERFORM FINAL-PARA. MAIN-PARA. CALL 'CBLTDLI' USING C-GU, IO-PCB, IO-IN-AREA MOVE IN-PATNO TO SSA-ARG MOVE IO-STAT TO OUT-IO-STAT CALL 'CBLTDLI' USING C-GU, PCBMASK, SEG-IO-AREA, SSA-Q MOVE DB-STAT TO OUT-DB-STAT MOVE DB-PATNO TO OUT-PATNO MOVE DB-NAME TO OUT-NAME MOVE DB-ADDRESS TO OUT-ADDRESS CALL 'CBLTDLI' USING C-ISRT, IO-PCB, IO-OUT-AREA. FINAL-PARA. GOBACK. A100-EXIT. EXIT.

IMS DC PROGRAMMING

01/08/2004

Page 110/ 115

Test Data

PATIENT ILLNESS TREATMNT BILLING PAYMENT HOUSHLD PATIENT ILLNESS TREATMNT BILLING PAYMENT PAYMENT HOUSHLD PATIENT ILLNESS TREATMNT BILLING PAYMENT HOUSHLD PATIENT ILLNESS TREATMNT BILLING PAYMENT PAYMENT HOUSHLD PATIENT ILLNESS TREATMNT BILLING PAYMENT HOUSHLD

00001ABCDEF1 18,CHN 600023-1 01012000MALARIA 01012000QUININE 0004DR.DOBBS 000600 000600 MOHAN FATHER 00002ABCDEF2 18,CHN 600023-2 01012000JAUNDICE 01012000AYURVEDIC 0004DR.JAMES 000500 000400 000100 MEERA MOTHER 00003ABCDEF3 18,CHN 600023-3 01012000FLU 01012000CROCIN 0004DR.PILOO 000400 000400 JAYA SISTER 00004ABCDEF4 18,CHN 600023-4 01012000MEASLES 01012000NEEMLEAVES0004DR.TOM 000300 000200 000100 MAYA SISTER 00005ABCDEF5 18,CHN 600023-5 01012000TYPHOID 01012000ANTIBIOTIC0004DR.YOUNG 000200 000200 LATA SISTER

The following need customization where shown in back lighted blue PSBGEN PROC
// PROC MBR=TEMPNAME,SOUT=A,RGN=0M,SYS2= //C EXEC PGM=ASMA90,REGION=&RGN, // PARM='OBJECT,NODECK,NODBCS' //SYSLIB DD DSN=IMS.&SYS2.MACLIB,DISP=SHR //SYSLIN DD UNIT=SYSDA,DISP=(,PASS), // SPACE=(80,(100,100),RLSE), // DCB=(BLKSIZE=80,RECFM=F,LRECL=80) //SYSPRINT DD SYSOUT=&SOUT,DCB=BLKSIZE=1089, // SPACE=(121,(300,300),RLSE,,ROUND) //SYSUT1 DD UNIT=SYSDA,DISP=(,DELETE), // SPACE=(CYL,(10,5)) //L EXEC PGM=IEWL,PARM='XREF,LIST', // COND=(0,LT,C),REGION=120K //SYSLIN DD DSN=*.C.SYSLIN,DISP=(OLD,DELETE) //SYSPRINT DD SYSOUT=&SOUT,DCB=BLKSIZE=1089, // SPACE=(121,(90,90),RLSE)

IMS DC PROGRAMMING //SYSLMOD // //SYSUT1 //

01/08/2004

Page 111/ 115

DD DISP=SHR, DSN=USER01.PSBLIB(&MBR) DD UNIT=(SYSDA,SEP=(SYSLMOD,SYSLIN)), SPACE=(1024,(100,10),RLSE),DISP=(,DELETE)

DBDGEN PROC

// PROC MBR=TEMPNAME,SOUT=A,RGN=0M,SYS2= //C EXEC PGM=ASMA90,REGION=&RGN, // PARM='OBJECT,NODECK,NODBCS' //SYSLIB DD DSN=IMS.&SYS2.MACLIB,DISP=SHR //SYSLIN DD UNIT=SYSDA,DISP=(,PASS), // SPACE=(80,(100,100),RLSE), // DCB=(BLKSIZE=80,RECFM=F,LRECL=80) //SYSPRINT DD SYSOUT=&SOUT,DCB=BLKSIZE=1089, // SPACE=(121,(300,300),RLSE,,ROUND) //SYSUT1 DD UNIT=SYSDA,DISP=(,DELETE), // SPACE=(CYL,(10,5)) //L EXEC PGM=IEWL,PARM='XREF,LIST', // COND=(0,LT,C),REGION=120K //SYSLIN DD DSN=*.C.SYSLIN,DISP=(OLD,DELETE) //SYSPRINT DD SYSOUT=&SOUT,DCB=BLKSIZE=1089, // SPACE=(121,(90,90),RLSE) //SYSLMOD DD DISP=SHR, // DSN=USER01.DBDLIB(&MBR) //SYSUT1 DD UNIT=(SYSDA,SEP=(SYSLMOD,SYSLIN)), // SPACE=(1024,(100,10),RLSE),DISP=(,DELETE)

IGYWCL PROC (modified to suit IMS)

//IGYWCL PROC LNGPRFX='IGY.V2R1M0',SYSLBLK=3200, // LIBPRFX='CEE', // PGMLIB='&&GOSET',GOPGM=GO //COBOL EXEC PGM=IGYCRCTL,REGION=2048K //STEPLIB DD DSNAME=&LNGPRFX..SIGYCOMP, // DISP=SHR //SYSPRINT DD SYSOUT=* //SYSLIN DD DSNAME=&&LOADSET,UNIT=SYSDA, // DISP=(MOD,PASS),SPACE=(TRK,(3,3)), // DCB=(BLKSIZE=&SYSLBLK) //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSUT5 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSUT6 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSUT7 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //LKED EXEC PGM=HEWL,COND=(8,LT,COBOL),REGION=1024K //SYSLIB DD DSNAME=&LIBPRFX..SCEELKED,DISP=SHR //RESLIB DD DSNAME=IMS.RESLIB,DISP=SHR //SYSPRINT DD SYSOUT=* //SYSLIN DD DSNAME=&&LOADSET,DISP=(OLD,DELETE) // DD DSNAME=USER01.PROCLIB(CBLTDLI),DISP=SHR // DD DDNAME=SYSIN //SYSLMOD DD DSNAME=&PGMLIB(&GOPGM), // SPACE=(TRK,(10,10,1)), // UNIT=SYSDA,DISP=(MOD,PASS)

IMS DC PROGRAMMING //SYSUT1 DD

01/08/2004 UNIT=SYSDA,SPACE=(TRK,(10,10))

Page 112/ 115

MFSUTL
// PROC RGN=360K,SOUT=A,SNODE=yournode, // MBR=NOMBR,PXREF=NOXREF, // PCOMP=NOCOMP,PSUBS=NOSUBS,PDIAG=NODIAG, // COMPR=NOCOMPRESS,COMPR2=COMPRESS, // LN=55,SN=8,DEVCHAR=0,COMPR3=NOCOMPREND, // DIRUPDT=UPDATE //S1 EXEC PGM=DFSUPAA0,REGION=&RGN, // PARM=(&PXREF,&PCOMP,&PSUBS,&PDIAG,&COMPR, // 'LINECNT=&LN,STOPRC=&SN,DEVCHAR=&DEVCHAR') //STEPLIB DD DSN=IMSVS.&SNODE..RESLIB,DISP=SHR //*SYSLIB - USER OPTION //SYSIN DD DSN=USER01.MFS.SOURCE(&MBR),DISP=SHR //REFIN DD DSN=USER01.REFERAL,DISP=OLD //REFOUT DD DSN=USER01.REFERAL,DISP=OLD //REFRD DD DSN=USER01.REFERAL,DISP=OLD //SYSTEXT DD DSN=&&TXTPASS,UNIT=SYSDA, // SPACE=(CYL,(1,1)),DCB=BLKSIZE=800 //SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //DUMMY DD DSN=IMSVS.&SNODE..PROCLIB(REFCPY),DISP=SHR //UTPRINT DD SYSOUT=&SOUT //SYSPRINT DD SYSOUT=&SOUT,DCB=(RECFM=FBA,LRECL=133,BLKSIZE=1330) //SYSUDUMP DD SYSOUT=&SOUT //SEQBLKS DD DSN=&&BLKS,DISP=(NEW,PASS), // UNIT=SYSDA,SPACE=(CYL,(1,1)) //S2 EXEC PGM=DFSUNUB0,REGION=&RGN, // PARM=(&COMPR2,&COMPR3,&DIRUPDT, // 'DEVCHAR=&DEVCHAR'),COND=(8,LT,S1) //STEPLIB DD DSN=IMSVS.&SNODE..RESLIB,DISP=SHR //SEQBLKS DD DSN=&&BLKS,DISP=(OLD,DELETE) //UTPRINT DD SYSOUT=&SOUT,DCB=(RECFM=FBA,LRECL=133,BLKSIZE=1330) //SYSUDUMP DD SYSOUT=&SOUT //FORMAT DD DSN=USER01.TFORMAT,DISP=SHR //DUMMY DD DSN=IMSVS.&SNODE..PROCLIB(FMTCPY),DISP=SHR //SYSPRINT DD SYSOUT=&SOUT //SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(1,1)) //SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,(1,1))

DLIBATCH
// // // // // // //* // // //G // // // // PROC MBR=TEMPNAME,PSB=,BUF=7, SPIE=0,TEST=0,EXCPVR=0,RST=0,PRLD=, SRCH=0,CKPTID=,MON=N,LOGA=0,FMTO=T, IMSID=,SWAP=,DBRC=,IRLM=,IRLMNM=, BKO=N,IOB=,SSM=,APARM=, RGN=2048K, SOUT=A,LOGT=2400,SYS2=, SOUT=A,SYS2=, LOCKMAX=,GSGNAME=,TMINAME= EXEC PGM=DFSRRC00,REGION=&RGN, PARM=(DLI,&MBR,&PSB,&BUF, &SPIE&TEST&EXCPVR&RST,&PRLD, &SRCH,&CKPTID,&MON,&LOGA,&FMTO, &IMSID,&SWAP,&DBRC,&IRLM,&IRLMNM,

IMS DC PROGRAMMING // // //STEPLIB // // //DFSRESLB //IMS // //PROCLIB //IEFRDER // // //SYSUDUMP // // //IMSMON

01/08/2004

Page 113/ 115

&BKO,&IOB,&SSM,'&APARM', &LOCKMAX,&GSGNAME,&TMINAME) DD DSN=IMS.&SYS2.RESLIB,DISP=SHR DD DSN=IMS.&SYS2.PGMLIB,DISP=SHR DD DSN=USER01.LOADLIB,DISP=SHR DD DSN=IMS.&SYS2.RESLIB,DISP=SHR DD DSN=USER01.PSBLIB,DISP=SHR DD DSN=USER01.DBDLIB,DISP=SHR DD DSN=IMS.&SYS2.PROCLIB,DISP=SHR DD DSN=USER01.IMSLOG,DISP=(NEW,KEEP), DCB=(RECFM=VB,BLKSIZE=1920, LRECL=1916,BUFNO=2),SPACE=(TRK,(1,1)) DD SYSOUT=&SOUT, DCB=(RECFM=FBA,LRECL=121,BLKSIZE=605), SPACE=(605,(500,500),RLSE,,ROUND) DD DUMMY

BTS

//BTS PROC KW=DLI, REGION TYPE // BUF=, ISAM/OSAM BUFFER POOL SIZE // SPIE=0,TEST=0, * // EXCPVR=0,RST=0, * SEE // PRLD=, * IMS/VS // SRCH=0, * MANUALS // CKPTID=, * FOR // MON=N, * THESE // LOGA=0, * PARMS // FMTO=T, * // IMSID=, * // SWAP=, * // DBRC=N, * // IOSEG=512, MAXIMUM IO PCB SEGMENT SIZE // IOBLK=3072, MAXIMUM MESSAGE QUEUE BLOCK SIZE // ALTSEG=536, MAXIMUM ALTERNATE PCB SEGMENT SIZE // IMS=XXXXXXXX, MIDDLE QUALIFIER OF DATASET // SOUT=A SYSOUT CLASS //* //G EXEC PGM=BTSRC000,REGION=512K, // PARM=(&KW,&BUF,&SPIE&TEST&EXCPVR&RST,&PRLD,&SRCH, // &CKPTID,&MON,&LOGA,&FMTO,&IMSID,&SWAP,&DBRC) //DFSRESLB DD DISP=SHR,DSN=IMSVS.&IMS..RESLIB //STEPLIB DD DISP=SHR,DSN=IMSVS.BTSLIB // DD DISP=SHR,DSN=IMSVS.&IMS..RESLIB // DD DISP=SHR,DSN=USER01.LOADLIB //IMS DD DISP=SHR,DSN=USER01.PSBLIB // DD DISP=SHR,DSN=USER01.DBDLIB //FORMAT DD DSN=USER01.TFORMAT,DISP=SHR //IEFRDER DD DUMMY //SYSUDUMP DD SYSOUT=&SOUT //BTSOUT DD SYSOUT=&SOUT, // DCB=(RECFM=FBA,LRECL=133,BLKSIZE=133) //BTSSNAP DD SYSOUT=&SOUT,SPACE=(TRK,(10,15)) //QIOPCB DD UNIT=SYSDA,SPACE=(CYL,1), // DCB=(LRECL=&IOSEG,BLKSIZE=&IOBLK) //QALTPCB DD UNIT=SYSDA,SPACE=(CYL,1), // DCB=(LRECL=&IOSEG,BLKSIZE=&IOBLK)

IMS DC PROGRAMMING //QALTRAN //BTSIN

01/08/2004

Page 114/ 115

DD UNIT=SYSDA,SPACE=(CYL,1),DCB=BLKSIZE=&ALTSEG DD DUMMY

DBD Generation

//USER011 JOB NOTIFY=&SYSUID,CLASS=A,MSGLEVEL=(1,1),REGION=0M // JCLLIB ORDER=(USER01.PROCLIB) //STEP1 EXEC DBDGEN,MBR=memname //C.SYSIN DD DSN=USER01.DBD.SOURCE(memname),DISP=SHR //

PSB Generation

//USER011 JOB NOTIFY=&SYSUID,CLASS=A,MSGLEVEL=(1,1),REGION=0M // JCLLIB ORDER=(USER01.PROCLIB) //STEP1 EXEC PSBGEN,MBR=memname //C.SYSIN DD DSN=USER01.PSB.SOURCE(memname),DISP=SHR //

IDCHIS

IDCAMS Job Stream to create the clusters

//USER011 JOB NOTIFY=&SYSUID,CLASS=A,MSGLEVEL=(1,1) // JCLLIB ORDER=(USER01.PROCLIB) //STEP1 EXEC PGM=IDCAMS //SYSPRINT DD SYSOUT=* //SYSIN DD * DELETE USER01.PNTDBHIS CLUSTER DELETE USER01.PNTOVFLW CLUSTER DEFINE CLUSTER (NAME(USER01.PNTOVFLW) NONINDEXED RECORDSIZE(52,52) TRACKS(1,1) CONTROLINTERVALSIZE(2048)) DEFINE CLUSTER (NAME(USER01.PNTDBHIS) INDEXED KEYS(5,6) RECORDSIZE(52,52) TRACKS(1,1)) DATA(CONTROLINTERVALSIZE(2048)) //

COBOL Compilation
//USER011 JOB NOTIFY=&SYSUID,CLASS=A,MSGLEVEL=(1,1) // JCLLIB ORDER=(USER01.PROCLIB) //STEP1 EXEC IGYWCL,REGION=0M //COBOL.SYSIN DD DSN=USER01.COBOL.SOURCE(LOADPGM),DISP=SHR //LKED.SYSLMOD DD DSN=USER01.LOADLIB(LOADPGM),DISP=SHR //

MFS JCL

//USER01L JOB (XXXXXX),NOTIFY=&SYSUID,CLASS=X // JCLLIB ORDER=(USER01.PROCLIB) //JS010 EXEC MFSUTL,MBR=TEST1 //

IMSRUN

//USER011 JOB NOTIFY=&SYSUID,CLASS=A,MSGLEVEL=(1,1) // JCLLIB ORDER=(USER01.PROCLIB) //STEP1 EXEC DLIBATCH,MBR=LOADPGM,PSB= PNTPHISL,DBRC=N //G.SYSPRINT DD SYSOUT=* //* //* THIS IS FOR THE HISAM PATIENT DATABASE //G.PNTDBHIS DD DSN=USER01.PNTDBHIS,DISP=SHR

IMS DC PROGRAMMING

01/08/2004

Page 115/ 115

//G.PNTOVFLW DD DSN=USER01.PNTOVFLW,DISP=SHR //* //* THIS IS THE LOAD DATA FOR PATIENT DATABASE //G.SYSIN DD DSN=USER01.LOAD.DATA(DATA),DISP=SHR //* //G.DFSVSAMP DD * VSRBF=2048,4 /* //

BTSRUNB

//USER01R JOB (xxxxxx),NOTIFY=&SYSUID,CLASS=X,MSGLEVEL=(1,1) // JCLLIB ORDER=(USER01.PROCLIB) //STEP1 EXEC BTS //G.SYPRINT DD SYSOUT=* //G.BTSIN DD * ./T TC=DUMMY MBR=READPGM PSB=PNTPHISG LANG=CBL TYPE=DLI DUMMY $ /* //* THIS IS FOR THE HISAM PATIENT DATABASE //G.PNTDBHIS DD DSN=USER01.PNTDBHIS,DISP=SHR //G.PNTOVFLW DD DSN=USER01.PNTOVFLW,DISP=SHR //* //G.DFSVSAMP DD * VSRBF=2048,4 /* //

BTSRUNO
//USER01R JOB (xxxxxx),NOTIFY=&SYSUID,CLASS=X,MSGLEVEL=(1,1) // JCLLIB ORDER=(USER01.PROCLIB) //STEP1 EXEC BTS //G.SYPRINT DD SYSOUT=* //G.BTSIN DD * ./D TYPE=3270-A2 SIZE=(24,80) ./O ATR=NO ./T TC=READPGMO MBR=READPGMO PSB=PNTPHISG LANG=CBL TYPE=MSG /FOR TEST1O L06C25 '00001' ENTER $ /* //* THIS IS FOR THE HISAM PATIENT DATABASE //G.PNTDBHIS DD DSN=USER01.PNTDBHIS,DISP=SHR //G.PNTOVFLW DD DSN=USER01.PNTOVFLW,DISP=SHR //* //G.DFSVSAMP DD * VSRBF=2048,4 /* //