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.
In MVS, PSBs are stored as members of a partitioned dataset. FOCPSBs are also stored as members of a partitioned dataset. The member name for a FOCPSB must be identical to the member name of its corresponding PSB.
If your operating system is DOS/VSE, the FOCPSB file must be a sequential VSAM ESDS dataset created with RECFM F.
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.
Note:
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.
Each FOCPSB starts with a header record. The syntax is
FOCPSB=EXTENDED [,PL1=YES] ,$
where:
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:
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 Chapter 4, 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 is shown:
FOCPSB=EXTENDED,$
PCBNAME= ,PCBTYPE=TERM,$
PCBNAME= ,PCBTYPE=TERM,$
PCBNAME= ,PCBTYPE=TERM,$
PCBNAME=PATINFO ,PCBTYPE=DB,$
PCBNAME=IXNAME ,PCBTYPE=DB,$
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 filename you reference in the request.
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:
Note:
The next section shows a sample FOCPSB with partitioning.
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 Interface can examine the report request and determine which PCBs satisfy the request. Without the partitioning information, the Interface 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:
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 Interface 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 Interface would have used the EMPDB01 and EMPDB02 PCBs.
Refer to Sample File Descriptions, for the corresponding DBD and Master File.
Note:
For MVS, each FOCPSB is stored as a member of a partitioned dataset (PDS); by convention, the FOCPSB dataset is named
prefix.FOCPSB.DATA
where:
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 Interface, and you only allocate that FOCPSB member in your CLIST or JCL. However, with the DBCTL environment, you allocate the entire FOCPSB dataset 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). Environments, discusses allocation of the FOCPSB dataset.
The current release of the IMS Interface has been enhanced to include a new exit IMDYNPCB. This exit allows you to indicate to the Interface 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:
When you issue a TABLE request against an IMS database, the Interface checks to see if a module named IMDYNPCB exists. If it exists, the IMDYNPCB module will be loaded, called and passed the parameters listed in the following section.
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".
Prior to issuing the first DL/I call, the Interface invokes the exit a second time with a "Call Type" value of "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 Interface to select the PCB for subsequent data retrieval.
After the IMS retrieval is complete (GE), the Interface invokes the exit a third time with a "Call Type" value of "E". This allows you to do final tasks prior to the Interface shutting down.
To use the IMDYNPCB exit you must do the following:
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
* 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
Information Builders |