x

The advantages of using DBCTL include the following:

• Direct communication between your application and IMS. Your task establishes its own connection to IMS by loading and calling the DBCTL subsystem when needed. It then issues DL/I calls directly to IMS. This implementation eliminates the need for a batch job (the XMI server), running in an additional address space, to intercept DL/I calls from FOCUS and transmit them to IMS.
• Enhanced security. You have access to standard security systems through the standard SAF interface (see Security). The SAF interface is supported by security products such as RACF, CA-TOP SECRET, and CA-ACF2. Before allowing access to a particular PSB, the system verifies that the user is authorized to read the PSB.
• Dynamic PSB selection and switching within your application. There are two methods for implementing dynamic PSB selection:

  In your JCL or CLIST, you can allocate ddname FOCPSB to a partitioned data set. Then, within your application, you can issue a SET command to select any member PSB from the data set

  You also have the option of creating Access Files that identify the appropriate PSB for each Master File (see Creating FOCUS Descriptions). When you have Access Files, you do not have to issue a command to select a PSB, so the selection is transparent to your application.

• Sharing of PCBs between applications. Multiple users can share the same PCBs, reducing the number of duplicate PCBs in a PSB and minimizing overhead.
• The ability to view current settings (PSB, IMSSEC, IMSCLASS, IMSMODE, IMSPZP) by issuing the IMS SET ? query command (seeRelease Dependent Adapter Features for an example).
• Access to most IMS databases (HDAM, HIDAM, Fast Path DEDB), except for Fast Path MSDB.

DBCTL must have been installed as described in Installation Instructions.

x

The following diagram illustrates the relationship between FOCUS, the adapter, and IMS in the DBCTL environment:

Address Space	Contains
1	FOCUS. The Adapter for IMS/DB. The DBCTL stub, a component of IMS.
2	The online IMS databases.

To invoke the adapter interactively within the DBCTL environment, edit the following CLIST to conform to the standards at your site. In addition, add the IMS.RESLIB and the name of the PDS that contains the DRA Startup Table (load module DFSPZPxx, described in Installation Instructions) to the STEPLIB allocation in your TSO logon procedure. Note that the CLIST allocates the entire FOCPSB data set, not just one member:

PROC 0
CONTROL NOMSG
FREE DDNAME(USERLIB ERRORS MASTER ACCESS FOCEXEC FOCPSB FOCLIB)
ALLOC F(ERRORS)   DA('prefix.ERRORS.DATA') SHR REUSE
ALLOC F(USERLIB)  DA('prefix.IMS.LOAD' +
                     'prefix.FUSELIB.LOAD') SHR REUSE
ALLOC F(MASTER)   DA('prefix.MASTER.DATA') SHR REUSE
ALLOC F(ACCESS)   DA('prefix.ACCESS.DATA') SHR REUSE
ALLOC F(FOCEXEC)  DA('prefix.FOCEXEC.DATA') SHR REUSE
ALLOC F(FOCPSB)   DA('prefix.FOCPSB.DATA') SHR REUSE
ALLOC F(FOCLIB)   DA('prefix.FOCLIB.LOAD') SHR REUSE
CALL 'prefix.FOCLIB.LOAD(FOCUS)'

where:

prefix

Is the high-level qualifier for your FOCUS production libraries.

You can omit the allocation for ddname ACCESS if you select the PSB name with the IMS SET PSB command, not in an Access File (see Implementing DBCTL).

To invoke the adapter as a batch job, submit the following JCL after editing it to conform to the standards at your site and adding a JOB card. Note that the JCL allocates the entire FOCPSB data set, not just one member:

//FOCDBCTL EXEC PGM=FOCUS,REGION=nn 
//STEPLIB  DD DSN=prefix.FOCLIB.LOAD,DISP=SHR
//         DD DSN=IMS.RESLIB,DISP=SHR
//         DD DSN=prefix.IMS.LOAD,DISP=SHR
//         DD DSN=prefix.FUSELIB.LOAD,DISP=SHR
//ERRORS   DD DSN=prefix.ERRORS.DATA,DISP=SHR
//FOCPSB   DD DSN=prefix.FOCPSB.DATA,DISP=SHR
//FOCEXEC  DD DSN=prefix.FOCEXEC.DATA,DISP=SHR
//MASTER   DD DSN=prefix.MASTER.DATA,DISP=SHR
//ACCESS   DD DSN=prefix.ACCESS.DATA,DISP=SHR
//SYSOUT   DD SYSOUT=*
//*FSTRACE  DD SYSOUT=*,DCB=BLKSIZE=133
//*FSTRACE4 DD SYSOUT=*,DCB=BLKSIZE=133
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
TSO IMS SET IMSPZP xx 
TSO IMS SET DBCTL ON
TSO IMS SET PSB psbname 
TABLE FILE ...
  .
  .
  .
END
FIN
/*
//

where:

nn

Is the region size.

prefix

Is the high-level qualifier for your FOCUS production libraries.

xx

Is the suffix for the DRA Startup Table, chosen during installation (see Installation Instructions).

psbname

Is the name of the PSB to use.

Note:

• The SET commands in the sample are described in Implementing DBCTL. You can omit the allocation for ddname ACCESS if you select the psbname with the IMS SET PSB command, as in the sample.
• IMS.RESLIB is the IMS load library, and 'prefix.IMS.LOAD' is the PDS that contains the DRA Startup Table (discussed in Installation Instructions) and the adapter load library.

x

To implement the DBCTL environment, issue the following commands in the order shown:

ENGINE IMS SET IMSPZP {xx|00}

ENGINE IMS SET DBCTL ON

where:

xx

Indicates the suffix for the DRA Startup Table, chosen during installation (see Installation Instructions). The default is 00.

Next, if you did not create an Access File to automatically select the PSB for your request (see Creating FOCUS Descriptions), or to change the selected PSB, issue the following command either from the command line or in a FOCEXEC

ENGINE IMS SET PSB psbname 

where:

psbname

Is the name of the FOCPSB library member to use. This name must be identical to the name of the actual PSB that IMS will access. If the member does not exist, the following error message is generated:

(FOC4261) FOCPSB MEMBER NOT FOUND: psbname

Note:

• All participating files in a join must use the same PSB. Any attempt to join files that require different PSBs generates the following error message:

  (FOC4295) ACCESS POINTS TO DIFFERENT PSBS IN JOIN

• The IMS SET PSB command supersedes the PSB attribute in the Access File.

To see the settings in effect at any time during your session, issue the following query command:

ENGINE IMS SET ?

Release Dependent Adapter Features contains an example of the IMS SET ? query command.