EGL support for runtime PSBs and PCBs

This topic concerns tasks that are appropriate in the following cases:

When the target for EGL generation is IMS™ BMP or IMS/VS; or
When your code is accessing DL/I databases, as is possible when the target system is CICS®, IMS/VS, IMS™ BMP, or z/OS® batch; or
When your code is accessing GSAM files, as is possible when the target system is IMS™ BMP or z/OS® batch.

You customize EGL program elements as needed to generate a COBOL program that can access your organization's program specification blocks (PSBs) and program communication blocks (PCBs). Those blocks are called the runtime PSBs and runtime PCBs.

First, define the DLISegment record parts that you will reference in database PCB records (if any). Your next, primary tasks are as follows:

Define a PSB record part. That part includes the set of PCB records that will be used when accessing IMS™ message queues, DL/I databases, or GSAM files.
In the program, make the PSB and PCB information available:
- Declare a record that is based on the PSB record part
- Set the program property @dli, property field psb to the name of the PSB record; for more information on the syntax, see Set-values blocks.

Each PCB record is based on one of the following, predefined PCB record parts:

IO_ PCBRecord

Used to interact with an I/O PCB, which allows for input from a program or terminal and (if the input came from a terminal) allows for output to the same terminal. The I/O PCB also provides access to other IMS™ capabilities; for example, checkpoint and restart of a batch program.

ALT_PCBRecord

Used to reference a teleprocessing PCB other than the I/O PCB. This type of record allows your code to write output to a message queue that is associated either with another transaction or with a device other than the terminal associated with the I/O PCB. The runtime PCB may be either of the following kinds:

An alternate PCB, in which case the message is sent to its destination only if a commit occurs; or
An express alternate PCB, in which case the message is sent to its destination regardless of whether a commit or rollback occurs.

DB_PCBRecord

Used to reference a database PCB, which represents a DL/I database accessible from your program. The runtime database PCB specifies the data that can be accessed and the type of access that is valid.

GSAM_PCBRecord

Used to reference a GSAM PCB, which is used when a z/OS® batch or IMS™ BMP program accesses a serial file that acts as a root-only DL/I database.

The next list provides details on the runtime PSB in each of the target systems.

CICS®

The value of the PSB record property defaultPSBName is (by default) the name of the runtime PSB. EGL places that name in the psbName field of the system variable dliLib.psbData, but you can assign a different value to that library field. When your program attempts an I/O operation against a DL/I database, the value in psbName determines what runtime PSB is used.

The system variable dliLib.psbData has a second field, psbRef. The initial value of the field is zero, which indicates that no PSB is scheduled. When the first DL/I I/O occurs, EGL runtime issues a PSB schedule call, which acts as follows:

Uses the value in dliLib.psbData.psbName to schedule a runtime PSB.
Sets dliLib.psbData.psbRef to an address with which that PSB can be accessed.

Note:

You must avoid writing logic that assigns any value to dliLib.psbData.psbRef.

During a call, you can use the variable dliLib.psbData to "pass the PSB" (really, to pass a name and the related address).

During a transfer, details of runtime behavior depend on how the transfer occurs:

If the transfer is by a show statement with a returning clause or by a transfer to transaction statement, the scheduled PSB ends because a commit point occurs during the transfer, and a PSB is not passed to the target program.
If the transfer is by a transfer to program statement, the default behavior depends on whether a PSB is scheduled:
- If a PSB is not scheduled, no commit point occurs.
- If a PSB is scheduled, that PSB ends because a commit point occurs during the transfer, and a PSB is not passed to the target program. But in this case an alternative outcome is possible, with the benefit that you can minimize the difference in behavior when the transferring program is generated for CICS® as compared to when that program is generated for IMS/VS. The alternative outcome occurs when four conditions are met:
  - The target system is z/OS® CICS®;
  - The target program is generated by EGL;
  - The build descriptor option synchOnPgmTransfer is set to NO; and
  - The default PSB referenced in the PSB record of the transferring program is the same as the default PSB referenced in the PSB record of the target program.
  In this case, a commit point does not occur, and EGL passes the scheduled PSB to the target program.
  Note:
  The default PSB is the value of the defaultPSBName property, which is set in the PSB record part that is the basis of a program's PSB record. The default value of that property is the name of the record part. To see examples of PSB records, see DLISegment stereotype.

DB PCBs are valid in the runtime PSB.

IMS™ BMP

The PSB parameter in the runtime JCL identifies the runtime PSB used throughout the job step. Although you can customize the JCL at deployment time, EGL generates the default PSB parameter value in the runtime JCL by assigning the value of the PSB record property defaultPSBName.

For IMS™ BMP, EGL requires that the following PCBs be in the runtime PSB:

In the zero (first) position, the I/O PCB. Be sure that your IMS™ system programmer sets CMPAT to YES when developing the PSBGEN job, even if you are generating a batch-oriented BMP.
An alternate PCB, which is usually in the second position.
An express alternate PCB, which is usually in the third position.

DB and GSAM PCBs are also valid.

IMS/VS

The rules of IMS™ system definition ensure that the name of the main program is the name of the runtime PSB, which is available throughout the transaction.

For IMS/VS, EGL requires that the following PCBs be in the runtime PSB:

In the zero (first) position, the I/O PCB. Your IMS™ system programmer can set CMPAT to YES when developing the PSBGEN job, though the action is optional.
An alternate PCB, which is usually in the second position.
An express alternate PCB, which is usually in the third position.

DB PCBs are also valid.

If the value of build descriptor option workDBType is DLI (as is the default), set one of your runtime DB PCBs for the EGL work database, which is identified as ELAWORK either in the runtime PSB or as the name of the EGL PCB record.

Note:

It is recommended that you specify the last database PCB in your runtime PSB as ELAWORK so that, if you decide to change to an SQL work database, you can easily remove that PCB.

z/OS® batch

The PSB parameter in the runtime JCL identifies the runtime PSB used throughout the job step. Although you can customize the JCL at deployment time, EGL generates the default PSB parameter value by assigning the value of the PSB record property defaultPSBName.

For z/OS® batch, EGL requires that the first runtime PCB be the I/O PCB. Be sure that your IMS™ system programmer sets CMPAT to YES when developing the PSBGEN job.

In addition, EGL requires two additional PCBs of any type be present in the runtime PSB. DB and GSAM PCBs are valid, as are alternate PSBs. Your code cannot use the alternate PSBs, however; their validity allows use of the same runtime PSB for z/OS® batch and IMS™ BMP.

EGL adjusts for an initial two or three I/O and teleprocessing PCBs if they are declared in the PSB record but are not present in the runtime PSB. This adjustment allows you to generate the same program across different environments. In relation to CICS®, for example, EGL runtime ignores the initial I/O and alternate PCB records if they are present in your code.

Requirements for the PSB record part

The structure of your PSB record part is closely related to the structure of your runtime PSB, and two other issues are in play:

The target system affects which PCBs are required in the PSB record part, as described earlier.
The value of the program property @dli, property field callInterface (whether AIBTDLI or CBLTDLI) also affects the requirements for your PSB record part.

When callInterface is AIBTDLI

When the callInterface field is set to AIBTDLI (as is the default), access to a given runtime PCB is by PCB name, and the structure of the PSB record in your program does not need to reflect the structure of a runtime PSB. However, you must make the runtime PCBs available to EGL:

For IMS/VS, IMS™ BMP, or z/OS® batch, the first PCB in the runtime PSB must be an I/O PCB. IMS™ always uses the name IOPCB as the name of the I/O PCB;
For IMS/VS and IMS™ BMP, EGL uses the following names for the other required PCBs:
- ELAALT for the alternate PCB.
- ELAEXP for the express alternate PCB.
- ELAWORK if you use a DL/I database as the EGL work database in the IMS/VS environment, In this case, you do not need to include the database hierarchy information in the EGL PCB record, and your IMS™ system programmer should use the macro ELAPCB when defining the runtime PSB, as shown later. (At generation time, you indicate that the work database is a DL/I database by accepting the default value for the build descriptor option workDBType.)
You can specify the names for those PCBs in one of the following ways:
- Ask your IMS™ system programmer to specify the EGL-required PCB name in the PSBGEN job that creates the runtime PSB. The following example uses a label to provide the name for the alternate PCB and includes the PCBNAME parameter to provide the name for the express alternate PCB and work database PCB:
```
ELAALT   PCB    TYPE=TP,MODIFY=YES
         PCB    TYPE=TP,MODIFY=YES,EXPRESS=YES,PCBNAME=ELAEXP
         ELAPCB LABEL=ELAWORK 
```
  In this case, you do not need to include the PCB records in your PSB record part.
- If your IMS™ programmer uses different names from those required by EGL, you must include the required PCB records in your PSB record part and must associate the EGL-required name with the name in your runtime PSB. Assume, for example, that your runtime PSB includes the following PCBs:
```
         PCB    TYPE=TP,MODIFY=YES,PCBNAME=MYALTPCB
         PCB    TYPE=TP,MODIFY=YES,EXPRESS=YES,PCBNAME=MYEXPPCB
         ELAPCB LABEL=MYWORKDB
```
  In this case, your PSB record part includes the PCB records as follows:
```
Record MYPSB type PSBRecordPart 		
   ELAALT ALT_PCBRecord {@PCB {pcbType = PCBKind.TP, PCBName = "MYALTPCB"}};
   ELAEXP ALT_PCBRecord {@PCB {pcbType = PCBKind.TP, PCBName = "MYEXPPCB"}};
   ELAWORK DB_PCBRecord {@PCB {pcbType = PCBKind.DB, PCBName = "MYWORKDB"}};
end 
```

When the callInterface field is set to AIBTDLI, you need to declare only the PCB records that are used in your program, as well as any of the required PCBs that have a different runtime name from the EGL-required name. This rule applies to main and called programs.

When callInterface is CBLTDLI

If you set the callInterface field to CBLTDLI, access to a given runtime PCB is by address rather than by name.

With the exception of I/O and alternate PCB records that EGL ignores so you can generate the same program across different environments, the structure of the PSB record in a main program must reflect at least the initial PCBs in the runtime PSB:

The PSB record cannot have more PCB records than the number of PCBs in the runtime PSB but can have fewer
The position of each PCB record must match the position of the related runtime PCB and must be of the same type as that PCB

If the target system is IMS/VS and you are using a DL/I database as the EGL work database, you do not need to include the database hierarchy information in the EGL PCB record, and your IMS™ system programmer should use the macro ELAPCB when defining the runtime PSB. (At generation time, you indicate that the work database is a DL/I database by accepting the default value for the build descriptor option workDBType.)

The situation in called programs is as follows:

If you pass a PSB record to the called program, you are passing an address used to access the runtime PSB. You must set up at least the initial part of the PSB record part as you did in the main program, including the PCB records for the I/O, alternate, and alternate express PCBs (if used in a particular environment), as well as other PCB records needed in the called program. You also must set the program property @dli, property field psbParm.
If you pass PCB records to the called program (as is preferred), you are passing addresses used to access each runtime PCB. You still must set up at least the I/O, alternate, and alternate express PCBs (if used in a particular environment); but aside from those, you need to declare only the PCB records that are needed in the called program. You also must set the program property @dli, property field pcbParms.

If you specify properties pcbParms and psbParm in a called program, the PCB-specific addresses in the former override the equivalent addresses in the latter; the passed PSB record is ignored.

For main or called programs that are generated for IMS/VS or IMS™ BMP, the default behavior is as follows:

The second PCB record refers to the alternate PCB
The third PCB record refers to the express alternate PCB

If you use ELAALT as the name of a record other than the second or if you use ELAEXP as the name of a record other than the third, the name takes precedence; EGL assumes that the named PCB record refers to the appropriate type of runtime PCB.