The FOCPSB

An IMS PSB consists of PCBs. Each PCB represents a view of an IMS database. A FOCPSB describes a PSB to FOCUS and associates a Master File with each PCB in the PSB. Optionally, the FOCPSB can also partition and concatenate PCBs.

PSBs are stored as members of a partitioned dat aset. FOCPSBs are also stored as members of a partitioned data set. The member name for a FOCPSB must be identical to the member name of its corresponding PSB.

A FOCPSB is a comma-delimited, free format file that consists of attributes (keyword=value pairs). Rules for declarations are as follows:

The following sections summarize the syntax for each type of declaration and then present detailed explanations for each attribute.

Required FOCPSB Attributes

In this section:

The required FOCPSB attributes describe the PSB to FOCUS and associate a Master File with each PCB you will access.

Extended FOCPSB Attributes describes additional attributes for partitioning and concatenating PCBs.

Top of page

The Header Record

Each FOCPSB starts with a header record. The syntax is

FOCPSB=EXTENDED  [,PL1=YES] ,$

where:

FOCPSB=EXTENDED

Indicates that the FOCPSB is in comma-delimited format.

PL1=YES

Optionally, indicates that the PSB was created for a PL/I application program. You must include this attribute when the IMS PSB specifies LANG=PLI, otherwise, omit it.

Note that you must code the attribute exactly as shown, with the numeric digit 1 in PL1 and the value YES.

Top of page

The PCB Record

Each PCB in the PSB must have a corresponding record in the FOCPSB. The order of PCB records in the FOCPSB must correspond to the order of the PCBs in the PSB.

If any PCB in the PSB includes the attribute LIST=NO, do not include a corresponding record for that PCB in the FOCPSB.

The syntax for a PCB record in the FOCPSB is

PCBNAME=mfdname,PCBTYPE=DB [,LOWVALUE=val1] [,HIGHVALUE=val2],$
PCBNAME=, PCBTYPE={TERM|SKIP} [,LOWVALUE=val1] [,HIGHVALUE=val2],$

where:

PCBNAME=mfdname

Indicates the one- to eight-character name of the Master File for the corresponding database PCB (PCBTYPE=DB). To report from the PCB, specify TABLE FILE mfdname.

PCBNAME=

Applies when no Master File is necessary (see TERM or SKIP for details).

TERM

Indicates that the corresponding PCB is an I/O PCB. (You need an I/O PCB to connect to IMS online through a teleprocessing monitor such as IMS/DC.) All I/O PCBs must be listed before any database PCB. Since no Master File is necessary, PCBNAME is blank.

Note that if the IMS PSB specifies CMPAT=YES, an I/O PCB is automatically generated at the top of the PSB for batch checkpointing. In this case, you must add an additional I/O PCB at the top of the FOCPSB.

SKIP

Indicates that you will not access the corresponding PCB. Since no Master File is necessary, PCBNAME is blank. Note that SKIP is a reserved word for the FOCPSB.

Important: Never use SKIP as a Master File name.

val1

Is used for partitioning. See Extended FOCPSB Attributes for a complete discussion.

val2

Is used for partitioning. See Extended FOCPSB Attributes for a complete discussion.

A PSB can have duplicate PCBs that provide identical views of an IMS database. Give each of these identical PCBs the same PCBNAME value in the FOCPSB. Certain environments, such as the XMI server environment, use this technique to give multiple users concurrent access to a database (see Environments). You can also use duplicate PCBs to facilitate a recursive join (see Reporting Efficiencies).

The following is an IMS PSB named TSTPSB01. It has two database PCBs that access the PATDB01 database, the first through the primary index, and the second through a secondary index named IXNAME (see Using a Secondary Index for information on describing secondary indexes in the FOCPSB):

PCB       TYPE=TP,MODIFY=YES,EXPRESS=YES
PCB       TYPE=TP,EXPRESS=NO,MODIFY=YES,SAMETRM=YES
PCB       TYPE=DB,DBDNAME=PATDB01,PROCOPT=GO,KEYLEN=9
SENSEG    NAME=PATINFO,PARENT=0
PCB       TYPE=DB,DBDNAME=PATDB01,PROCOPT=GO,KEYLEN=28,PROCSEQ=PATDBIX1
SENSEG    NAME=PATINFO,PARENT=0
PSBGEN    LANG=COBOL,PSBNAME=TSTPSB01,CMPAT=YES
END

The corresponding FOCPSB follows:

FOCPSB=EXTENDED,$
PCBNAME=        ,PCBTYPE=TERM,$
PCBNAME=        ,PCBTYPE=TERM,$
PCBNAME=        ,PCBTYPE=TERM,$
PCBNAME=PATINFO ,PCBTYPE=DB,$
PCBNAME=IXNAME  ,PCBTYPE=DB,$

Extended FOCPSB Attributes

In this section:

IMS limits the size of its databases. A site that needs a larger database may be able to create several smaller databases by partitioning the large database based on root key values.

Using extended FOCPSB attributes, you can describe a partition to FOCUS, describe how to concatenate the parts, and assign a name to the concatenated PCB. When you issue a report request, you can report from the concatenated PCB or from any of the individual partitions, depending on the file name you reference in the request.

Top of page

Describing a Partition in the FOCPSB

A partition assigns each record to a specific database depending on its root key value. The first partition contains records with the lowest key values. The next partition contains records with higher key values, and so on. The last partition contains records with the highest key values. Each partition is a separate IMS database and, therefore, has a separate PCB in the PSB. Partitioning is not supported for HDAM databases.

To describe the key range in each partition to FOCUS, add the LOWVALUE and HIGHVALUE attributes to the appropriate PCB records in the FOCPSB. The syntax is

PCBNAME=mfdname, PCBTYPE=DB, LOWVALUE= {val1|0} ,HIGHVALUE= {val2|FF},$

where:

mfdname: Is the name of the Master File for one partition of the large database. (Since the partition is a separate database with its own DBD, it needs its own PCB and Master File.)
val1: Is the lowest key value, in alphanumeric format, in the partition accessed with Master File mfdname. The default is 0.
val2: Is the highest key value, in alphanumeric format, in the partition accessed with Master File mfdname. The default is hexadecimal FF.

Note:

The LOWVALUE and HIGHVALUE attributes are ignored if you do not define a corresponding concatenation of the PCBs (see Describing a Concatenated PCB in the FOCPSB).
The number of partitions you can define for a database is limited by the number of PCBs in the PSB.
The partitioning field must be the key of the root segment.
The partitioning field must have alphanumeric format.
If the partitioning field is a group composed of multiple sub-fields, each sub-field value must be alphanumeric, and you must specify the concatenated sub-field values in the LOWVALUE and HIGHVALUE attributes. For example, if the root key low value is composed of F1=AAAA, F2=88, and F3=BBB, then LOWVALUE=AAAA88BBB.

Describing a Concatenated PCB in the FOCPSB shows a sample FOCPSB with partitioning.

Top of page

Describing a Concatenated PCB in the FOCPSB

In a FOCPSB, you can concatenate individual PCBs by assigning a name to the concatenation and issuing a report request against it.

The PCBs that you concatenate do not have to be partitioned. That is, their FOCPSB records do not have to include the LOWVALUE and HIGHVALUE attributes. However, if they do include the partitioning information, the adapter can examine the report request and determine which PCBs satisfy the request. Without the partitioning information, the adapter must access every PCB that participates in the concatenation.

To concatenate PCBs, include a CONCATNAME record after all PCBNAME records in the FOCPSB. The syntax is

CONCATNAME=cname, USE=mfd1/mfd2/.../mfdi ,$

where:

cname

Indicates the concatenation name. You can issue a request from the concatenated PCBs using the syntax TABLE FILE cname.

The CONCATNAME record can span more than one line. However, you cannot split an individual Master File name between two lines.

mfd1/.../mfdi

Are Master File names from the individual PCBNAME records in the FOCPSB. The key fields for all PCBs you concatenate must be the same length and type. You can issue a request from an individual PCB by referencing its individual Master File name in the request (for example, TABLE FILE mfd1).

The following example illustrates how to concatenate partitioned PCBs:

FOCPSB=EXTENDED,$
PCBNAME=   , PCBTYPE=TERM,$
PCBNAME=   , PCBTYPE=TERM,$
PCBNAME=   , PCBTYPE=TERM,$
PCBNAME=EMPDB01, PCBTYPE=DB, LOWVALUE=000000001, HIGHVALUE=000001667,$
PCBNAME=EMPDB02, PCBTYPE=DB, LOWVALUE=000001668, HIGHVALUE=000003334,$
PCBNAME=EMPDB03, PCBTYPE=DB, LOWVALUE=000003335, HIGHVALUE=000005000,$
CONCATNAME=EMPDBJ, USE=EMPDB01/EMPDB02/EMPDB03, $

Consider the following request (the key field is named SSNALPHA):

TABLE FILE EMPDBJ
.
.
.
IF SSNALPHA IS 000001775
.
.
.

The adapter satisfies the request using the EMPDB02 PCB only. If the WHERE clause had requested key values less than 000001775 (rather than equal to 000001775), the adapter would have used the EMPDB01 and EMPDB02 PCBs.

Refer to Sample File Descriptions for the corresponding DBD and Master File.

Note:

If a retrieval request has no WHERE clause, or if the WHERE clause references a non-key field, the adapter accesses all PCBs.
If any PCB listed in a concatenation lacks the LOWVALUE and HIGHVALUE key range specification, that PCB always participates in the retrieval.

The FOCPSB Data Set

Each FOCPSB is stored as a member of a partitioned data set (PDS). By convention, the FOCPSB dataset is named

prefix.FOCPSB.DATA

where:

prefix: Is the high-level qualifier used at your site for the FOCUS production libraries.

The member name for a FOCPSB within its PDS must be identical to the member name of the corresponding IMS PSB within its PDS. (IMS PSB library names have the form prefix1.prefix2.PSBLIB or prefix1.prefix2.ACBLIB.)

In most environments, you select the PSB to use before you invoke the adapter, and you only allocate that FOCPSB member in your CLIST or JCL. However, with the DBCTL environment, you allocate the entire FOCPSB data set and select a specific PSB during your session. You can implement this selection either dynamically (with a SET command) or by means of an Access File (see The Access File (DBCTL)). Environments discusses allocation of the FOCPSB data set.

Dynamic PCB Selection Exit

In this section:

The IMDYNPCB exit allows you to indicate to the adapter which PCB to use for retrieval based on a value in the selection criteria.

The exit is called three times during the execution of a TABLE request:

At setup time, prior to the TABLE request.
When you issue a TABLE request against an IMS database, the adapter checks to see if a module named IMDYNPCB exists. If it exists, the IMDYNPCB module is loaded, called and passed the parameters listed in the How to Use the IMDYNPCB Exit.

You can check the Call Type parameter in your code. It is the second parameter in the list. For the setup call, Call Type will contain the value S.

At run time, during the TABLE request execution.
Prior to issuing the first DL/I call, the adapter invokes the exit a second time with Call Type value R. Your code should use the information passed to it through the parameters and return a PCB number. This number will be used by the adapter to select the PCB for subsequent data retrieval.

At termination, at the end of the TABLE request.
After the IMS retrieval is complete (GE), the adapter invokes the exit a third time with Call Type value E. This allows you to do final tasks prior to the adapter shutting down.

Top of page

How to Use the IMDYNPCB Exit

To use the IMDYNPCB exit you must do the following:

Create an Assembler module that contains the following control block. The module must be named IMDYNPCB.

DYND     DSECT 
EYE      DS   CL7 
CALLTYPE DS   CL1   CALL TYPE can be S-startup, R-runtime, E-terminal
NUMPCBS  DS   F     Number of PCB's in the PSB 
PPCBLIST DS   A     Pointer to PCB list 
MFDNAME  DS   CL8   Master File name 
KEYNAME  DS   CL8   Key field name 
KEYLEN   DS   F     Key length 
PKEY     DS   A     Pointer to key value 
PCBNUM   DS   F     PCB number to use for data access
         DS   8F 
USERAREA DS   25F

Place the module in a load library allocated to ddname FOCLIB, USERLIB, or STEPLIB.

Top of page

IMDYNPCB Exit Sample

*  Dynamic PCB Selection user routine  
*  
*  This is a sample only. This code must be modified so that: 
*  When called with a calltype of: 
*  1) S, any initialization that is needed is processed. 
*  2) R, the routine must return in register 15 the pcb number to use  based on 
*        the key value passed in pkey. The first pcb in the psb  is 1, not 0.
*  3) E, any shutdown code is processed. Any system resources allocated  in  
*        startup must be freed here. 
*  In this example, a 9 byte key is examined and the pcb number to use 
*  is returned 
* 
         PRINT GEN 
IMDYNPCB startup code goes here (save regs in savearea (reg 13) )
         L     R3,0(R1)
         USING DYND,R3 
*
         XR    R7,R7             initialize return code 
* 
STARTUP  CLI   CALLTYPE,C'S'
         BNE   RUNTIME 
* 
*        PLACE STARTUP CODE HERE 
*
         B     IMDEND 
* 
RUNTIME  CLI   CALLTYPE,C'R'
         BNE   IMDCLOSE 
* 
*        TEST KEY VALUE PASSED AND SET R7 (WHICH WILL BE RETURNED) 
*        TO THE PCB NUMBER YOU WANT TO USE 
*
         L     R4,PKEY
         LA    R7,22
         CLC   0(9,R4),=C'000001667'
         BL    IMDEND
         LA    R7,23
         CLC   0(9,R4),=C'000003334'
         BL    IMDEND
         LA    R7,24
         B     IMDEND 
*

IMDCLOSE CLI   CALLTYPE,C'E'
         BNE   IMDEND 
* 
*        PLACE SHUTDOWN CODE HERE 
*
IMDEND   return, restore registers, set R15 to R7 and branch to R14 
*
         LTORG 
DYND     DSECT 
EYE      DS    CL7 
CALLTYPE DS    CL1    CALL TYPE can be S-startup, R-runtime, E-terminal 
NUMPCBS  DS    F      Number of PCB's in the PSB 
PPCBLIST DS    A      Pointer to PCB list 
MFDNAME  DS    CL8    Master File name 
KEYNAME  DS    CL8    Key field name 
KEYLEN   DS    F      Key length 
PKEY     DS    A      Pointer to key value 
PCBNUM   DS    F      PCB number to use for data access
         DS    8F USERAREA DS    25F
         END