Access to IMS Through DBCTL

IMS versions 3.1 and above offer the DBCTL (Database Control) facility for accessing online IMS databases in MVS. DBCTL provides a number of security, efficiency, and application control enhancements and is easy to implement.

This section includes the following topics:

• Advantages of DBCTL (see Advantages of DBCTL).
• How to invoke the Interface in the DBCTL environment (see Invoking the Interface in the DBCTL Environment).
• How to implement DBCTL in your FOCUS session (see Implementing DBCTL).

Note: DBCTL is not available for accessing IMS databases from CMS.

Advantages of DBCTL

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. In your JCL or CLIST, you allocate ddname FOCPSB to a partitioned dataset; 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 Chapter 3, 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 Interface 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.

Invoking the Interface in the DBCTL Environment

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

Address Space	Contains
1	Either MSO and FOCUS, or FOCUS without MSO. The IMS/DB Interface. The DBCTL stub, a component of IMS.
2	The online IMS databases.

To invoke the Interface interactively within the DBCTL environment, edit the following CLIST to conform to your site's standards. 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 site's FOCUS production libraries.

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

To invoke the Interface as a batch job, submit the following JCL after editing it to conform to your site's standards and adding a JOB card. Note that the JCL allocates the entire FOCPSB dataset, 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 site's 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 Section Implementing DBCTL, Implementing DBCTLDBCTL. 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 Interface load library.

Implementing DBCTL

To implement the DBCTL environment if you are not running MSO, issue the following commands in the order shown (if you are running MSO, these settings are in your configuration file, described in Installation Instructions):

{MVS|TSO} IMS SET IMSPZP {xx|00}

{MVS|TSO} 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 Chapter 3, Creating FOCUS Descriptions), or to change the selected PSB, issue the following command either from the command line, in the MSOPROF profile, or in a FOCEXEC

{MVS|TSO} 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:

{MVS|TSO} IMS SET ?

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