Data access using PSBs and PCBs

Use program specification blocks (PSBs) and program communication blocks (PCBs) to describe the logical structures in a program you generate for COBOL.

EGL represents PSBs with the PSBRecord stereotype. When you use this stereotype to customize a Record part, as with other Record parts, you then declare a variable based on the PSB record definition. In addition, EGL includes four kinds of PCB record definitions. Use PCB record definitions to declare PCB record variables within the PSB record definition.

You must also create the actual PSBs and PCBs in your COBOL environment. The information in these PSBs and PCBs must match the information in your EGL PSBs and PCBs.

The following situations require you to use PSBs and PCBs:

The target for EGL generation is IMS™ BMP or IMS/VS.
Your code accesses DL/I databases on CICS®, IMS/VS, IMS™ BMP, or z/OS® batch target systems.
Your code accesses GSAM files on IMS™ BMP or z/OS® batch target systems.

The following tasks are typical for data access using PSBs and PCBs:

If you are accessing a DL/I database, define the DLISegment records to reference in your PCB records.
Define a record with the PSBRecord stereotype. That record includes the set of PCB record variables that you use when accessing IMS™ message queues, DL/I databases, or GSAM files
In the program, make the PSB and PCB information available:
- Declare a variable based on the PSB record you defined in step 1.
- Set the psb property field of the @DLI program property to the name of that PSB record variable.

Each PCB record is based on one of the predefined PCB record definitions that EGL supplies; see PCB record stereotypes.

On certain platforms, you must declare an initial I/O PCB and at least one teleprocessing PCB. For more information, see "Compatibility" in this topic. If you declare those PCBs in the EGL PSB record and the runtime environment does not support the PCBs, the related EGL PCBs are not included in the generated COBOL.

For example, CICS® does not support I/O and teleprocessing PCBs. If your EGL PSB record includes these types of PCBs, they are ignored when you generate for CICS®. In this case, include the following property-field assignment when you code the complex property @DLI:

callInterface = DLICallInterfaceKind.CBLTDLI

That assignment adjusts the PCB number in DL/I calls to accommodate the lack of CICS® support for I/O and teleprocessing PCBs.

Requirements for the PSB record definition

The structure of your PSB record definition is related to the structure of your runtime PSB. Two other issues are also significant:

The target system affects which PCBs are required in the PSB record part (see "Compatibility" in this topic).
The value of the callInterface property field of the @DLI complex program property (whether AIBTDLI or CBLTDLI) also affects the requirements for your PSB record definition. For more information, see the next two sections of this topic.

When callInterface is AIBTDLI

When the callInterface property field is set to AIBTDLI (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 the corresponding 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, accept the default value for the workDBType build descriptor option to indicate that the work database is a DL/I database.
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. For example, assume 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 property 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 property field to CBLTDLI, access to a given runtime PCB is by address rather than by name.

Except for I/O and alternate PCB records, which EGL ignores so that 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 it 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 use 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 ELAPCB macro when defining the runtime PSB. At generation time, accept the default value for the workDBType build descriptor option to indicate that the work database is a DL/I database.

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 that you need in the called program. You must also set the psbParm property field for the @DLI program property.
If you pass PCB records to the called program (as is the best practice), 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). In addition to these, declare only the PCB records that are needed in the called program. You must also set the pcbParms property field for the @DLI program property.

If you specify the pcbParms and psbParm properties in a called program, the PCB-specific addresses in pcbParms override the equivalent addresses in psbParm; 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.

Compatibility

Table 1. Compatibility considerations for PSB records
Platform	Issue
Java™ generation	The PSBRecord stereotype is not supported.
CICS®	By default, the value of the defaultPSBName PSB record property is the name of the runtime PSB. EGL places that name in the psbName field of the dliLib.psbData system variable, 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 dliLib.psbData system variable 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, the EGL runtime issues a PSB schedule call; that call performs the following actions: Uses the value in dliLib.psbData.psbName to schedule a runtime PSB. Sets dliLib.psbData.psbRef to an address that can access that PSB. Avoid writing logic that assigns any value to dliLib.psbData.psbRef. During a call, use the dliLib.psbData variable to "pass the PSB" (to pass a name and the related address). During a transfer, the 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. In this case an alternative outcome is possible, which 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 all four of the following conditions are met: The target system is z/OS® CICS®. The target program is generated by EGL. The synchOnPgmTransfer build descriptor option is set to NO. 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. The default PSB is the value of the defaultPSBName property, which is set in the PSB record part that is the basis of a PSB record in the program. The default value of that property is the name of the record part. DB PCBs are valid in the runtime PSB.
IMS™ BMP	The PSB parameter in the runtime JCL identifies the runtime PSB that is 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 defaultPSBName PSB record property. 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 the workDBType build descriptor option is DLI (as is the default), set one of your runtime DB PCBs for the EGL work database. The EGL work database is identified as ELAWORK either in the runtime PSB or as the name of the EGL PCB record. For greatest flexibility, specify the last database PCB in your runtime PSB as ELAWORK. If you later 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 defaultPSBName PSB record property. 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 that 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.