DBCTL Instructions

In this section:

You can install the Interface to use the DBCTL subsystem of IMS if your site is running IMS version 3.1 or higher. Execute the following installation steps:

  1. Test your IMS DBCTL installation (see Test Your DBCTL Installation: IMDTST).
  2. Modify APPLCTN macros (see Modify APPLCTN Macros).
  3. Create the DRA Startup Table and place it in the 'prefix.IMS.LOAD' library. Concatenate this library ahead of IMS.RESLIB in the allocation for ddname STEPLIB (see Create the DRA Startup Table: DFSPZPxx).
  4. If you use MSO, select DBCTL mode by including the attribute DBCTL=START in the configuration file (see Create an MSO Configuration File and JCL for the DBCTL Environment).

Instructions for invoking DBCTL once it is installed are in Environments.


Top of page

x
Test Your DBCTL Installation: IMDTST

The IMDTST JCL, provided in the 'prefix.IMS.DATA' library, executes program IMDTEST to verify that DBCTL is properly installed. Run it before installing the IMS/DB Interface.

Note: If you are using IMS/ESA V3.1, make sure you have applied APAR PL70841.

The following is sample JCL for executing program IMDTEST

//job card goes here
//STEP1     EXEC PGM=IMDTEST,PARM='emppsb1,pcicspsb,xx',
//          REGION=4096K,TIME=(1,5)
//STEPLIB   DD DSN=prefix.IMS.LOAD,DISP=SHR
//          DD DSN=IMS.RESLIB,DISP=SHR
//SYSIN     DD DUMMY
//SYSOUT    DD SYSOUT=*
//SYSPRINT  DD SYSOUT=*

where:

emppsb1

Is the name of the PSB to schedule.

pcicspsb

Is a security class.

xx

Is a 2-character suffix that identifies the DRA Startup Module to be loaded, as described in Create the DRA Startup Table: DFSPZPxx.

Note: If you omit this parameter, its value defaults to 00, which may cause IMS to load the incorrect module.

prefix

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

After running the JCL, examine the JES output; the return codes displayed on the following lines indicate that DBCTL is properly installed:

JOB05736 +CCTL: JOBNAME(USERID1) PSB(EMPPSB1 ) CLASS(PCICSPSB) SUFFIX(5F)
JOB05736 +CCTL: INIT CALLED
JOB05736 +CCTL: INIT RETURNED,RETC(00000000)
JOB05736 +CCTL: WAITING FOR CONTROL EXIT
JOB05736 +CTLX: CONTROL EXIT CALLED
JOB05736 +CTLX: CONTROL EXIT RETURNED
JOB05736 +CCTL: INIT COMPLETED, FUNC(02) SFNC(00) RCOD(00) RETC(00000000)
JOB05736 +CCTL: SECURITY CHECK COMPLETED, RC(00000004)
JOB05736 +CCTL: TERMINATE DRA CALLED
JOB05736 +CTLS: SUSPEND EXIT CALLED
JOB05736 +CTLR: RESUME EXIT CALLED
JOB05736 +CTLS: SUSPEND EXIT RETURNED
JOB05736 +CTLR: RESUME EXIT RETURNED
JOB05736 +CCTL: TERMINATE DRA COMPLETED, RETC(00000000)

Note that the installation is successful even when the security check completes with a return code of 4.

If the JES output indicates an error, make sure of the following criteria:

See Create the DRA Startup Table: DFSPZPxx, for information about the DRA Startup Table.


Top of page

x
Modify APPLCTN Macros

Make sure all APPLCTN macros describing PSBs that will be accessed by multiple users specify SCHDTYP = Parallel. If necessary, modify the APPLCTN macros for such PSBs to include the attribute SCHDTYP = Parallel and re-run the IMS SYSGEN to make the changes effective.


Top of page

x
Create the DRA Startup Table: DFSPZPxx

In this section:

The Database Resource Adapter (DRA) is the interface between a user task and DBCTL. The DRA Startup Table contains values that define the characteristics of the DRA. The DRA Startup Table is named DFSPZPxx, where xx is a two-character suffix that should be chosen to comply with your site's standards.



x
Choose the Suffix for the DRA Startup Table

You must choose a suffix for the DRA Startup Table that complies with your site's standards. Once this suffix has been chosen, user applications must identify the chosen suffix to the Interface:



x
Assemble and Link the DRA Startup Table

Create the DRA Startup Table by specifying parameters in the DFSPRP macro of the DFSPZPxx module and then assembling and linking the DFSPZPxx module into the 'prefix.IMS.LOAD' library, as illustrated in the following sample JCL.

The sample JCL illustrates how to specify the parameters. You can normally find this JCL in your IMS installation library. A chart of the most common keywords and their descriptions follows the sample JCL.

//job card goes here
//ASSEMBLE EXEC  PGM=IEV90,REGION=2M,PARM='OBJECT,NODECK'
//SYSLIB   DD  DSN=IMS.MACLIB,DISP=SHR
//SYSLIN   DD  UNIT=SYSDA,DISP=(,PASS),
//             SPACE=(80,(100,100),RLSE),
//             DCB=(BLKSIZE=80,RECFM=F,LRECL=80)
//SYSPRINT DD  SYSOUT=*,DCB=BLKSIZE=1089
//SYSUT1   DD  UNIT=SYSDA,DISP=(,DELETE),
//             SPACE=(CYL,(10,5))
//SYSIN    DD  *
PRP      TITLE 'DATABASE RESOURCE ADAPTER STARTUP PARAMETER TABLE'
DFSPZPxx CSECT
         EJECT
         DFSPRP DSECT=NO,                                               X
               DBCTLID=IMS3,                                            X
               DDNAME=DFSRESLB,                                         X
               DSNAME=IMS.RESLIB,                                       X
               CNBA=150,                                                X
               MAXTHRD=150,                                             X
               MINTHRD=5
         END
/*
//*
//LINK   EXEC  PGM=IEWL,PARM='XREF,LIST',COND=(0,LT,ASSEMBLE),
//             REGION=4M
//SYSLIN   DD  DSN=*.ASSEMBLE.SYSLIN,DISP=(OLD,DELETE)
//SYSPRINT DD  SYSOUT=*,DCB=BLKSIZE=1089
//SYSUT1   DD  UNIT=(SYSDA,SEP=(SYSLMOD,SYSLIN)),
//             SPACE=(1024,(100,10),RLSE),DISP=(,DELETE)
//SYSLMOD  DD  DISP=SHR,DSN=prefix.IMS.LOAD(DFSPZPxx)

where:

prefix

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

xx

Is the two-character suffix chosen for the DRA Startup Table.

Note: The 'prefix.IMS.LOAD' library must be concatenated ahead of IMS.RESLIB in the allocation for ddname STEPLIB.

The following chart describes the most common keywords as defined for IMS/ESA Version 4. Other parameters that affect your IMS environment and that may be required at your site are described in the IBM IMS/ESA Version 4 System Definition Reference.

Keyword

Description

Default

AGN

A one- to eight-character application group name used as part of the DBCTL security function. For more information on DBCTL security, see the IMS/ESA System Administration Guide.

N/A

CNBA

The total number of Fast Path buffers for the MSO server's use. For a description of Fast Path DEDB buffer usage, see the IMS/ESA System Administration Guide. You can omit this parameter if your site does not utilize Fast Path.

N/A

DBCTLID

The four-character name of the DBCTL region. This is the same as the IMSID parameter in the DBC procedure. For more information on the DBC procedure, see the IBM IMS/ESA Version 3 System Definition Reference.

SYS1

DDNAME

Must be DFSRESLB. It is the ddname that will be allocated to the DBCTL RESLIB library (see the DSNAME keyword).

N/A

DSNAME

The one- to 44-character data set name of the DBCTL RESLIB library; it must contain the DRA modules and be MVS authorized.

IMS.RESLIB

FPBOF

The number of Fast Path DEDB overflow buffers to be allocated per thread. For a description of Fast Path DEDB buffer usage, see the IMS/ESA System Administration Guide. You can omit this parameter if your site does not utilize Fast Path.

00

FPBUF

The number of Fast Path DEDB buffers to be allocated and fixed per thread. For a description of Fast Path DEDB buffer usage, see the IMS/ESA System Administration Guide. You can omit this parameter if your site does not utilize Fast Path.

00

FUNCLV

The level of the DRA that the CCTL supports. FUNCLV=1 means the CCTL uses the DRA at the IMS 3.1 level.

1

MAXTHRD

The maximum number of concurrent DRA threads to be available. The maximum is 255.

1

MINTHRD

The minimum number of concurrent DRA threads to be available. Since the number of threads specified by this parameter will be allocated at all times, regardless of whether they are used, be careful in selecting this value. The maximum is 255.

1

SOD

The output class to use for a SNAP DUMP of abnormal thread termination.

A

TIMEOUT

The number of seconds a CCTL should wait for the successful completion of a DRA TERM request. Specify this value only if the CCTL is coded to use it. This value is returned to the CCTL upon completion of an INIT request.

60

TIMER

The number of seconds between attempts of the DRA to identify itself to DBCTL during an INIT request.

60

USERID

An eight character name of the CCTL region. No two CCTLs (MSO servers accessing the same IMS region through DBCTL) can have the same USERID (address space ID).

N/A



x
Create an MSO Configuration File and JCL for the DBCTL Environment

In this section:

From TSO, you select the DBCTL environment with a SET command (see Environments). To select the DBCTL environment from MSO, you must include the attribute DBCTL=START in the configuration file. This section illustrates a sample configuration file, sample MSO JCL, and instructions for controlling the DBCTL environment with console commands.



x
Sample Configuration File

The following sample configuration file includes the attributes needed for invoking DBCTL. Your system administrator can supply you with configuration file values, including IMSCLASS, that are specific to your site.

The MSO configuration file is allocated to ddname FOCMSO in the MSO server JCL

NUMFOC=1
MAXFOC=8
MSOLOG=ON
EXTSEC=ON
ATTNKEY=PA2
LU2_NAME=CICSE
******************************************************
** D B C T L   K E Y W O R D S                      **
******************************************************
IMSPZP=xx 
DBCTL=START
IMSSEC=ON
IMSCLASS=PCICSPSB
******************************************************
** S E R V I C E  ==  F O C U S                     **
******************************************************
SERVICE=FOCUS
PROGRAM=FOCUS
NUMBER_READY=0
MAXIMUM=30

where:

xx

Is the two-character suffix chosen for the DRA Startup Table, described in Create the DRA Startup Table: DFSPZPxx. If omitted, it defaults to 00.

Note: You must place the IMSPZP attribute before the DBCTL attribute.



x
Sample JCL

Use the following MSO server JCL as a model

//MSO      EXEC  PGM=SSCTL
//STEPLIB  DD DSN=prefix.FOCLIB.LOAD,DISP=SHR
//         DD DSN=prefix.FUSELIB.LOAD,DISP=SHR
//         DD DSN=prefix.IMS.LOAD,DISP=SHR
//         DD DSN=IMS.RESLIB,DISP=SHR
//ERRORS   DD DSN=prefix.ERRORS.DATA,DISP=SHR
//         DD DSN=prefix.IMS.DATA,DISP=SHR
//MSGET    DD DSN=prefix.MSO.MSOGET,DISP=SHR
//MSPUT    DD DSN=prefix.MSO.MSOPUT,DISP=SHR
//MSOPROF  DD DSN=prefix.MSOPROF.DATA,DISP=SHR   *MSO Profile FOCEXEC
//FOCSERVE DD DSN=prefix.FOCEXEC.DATA,DISP=SHR
//FOCEXEC  DD DSN=prefix.FOCEXEC.DATA,DISP=SHR
//FOCMSO   DD DSN=prefix.MSO.MSOCONFG,DISP=SHR   *MSO config file
//MASTER   DD DSN=prefix.MASTER.DATA,DISP=SHR
//ACCESS   DD DSN=prefix.ACCESS.DATA,DISP=SHR
//FOCPSB   DD DSN=prefix.FOCPSB.DATA,DISP=SHR
//MSOPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//

where:

prefix

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

Note: In the sample, ddname MSOPROF is allocated to the file that contains your MSO profile FOCEXEC. If you store this profile as a member of your 'prefix.FOCEXEC.DATA' library, allocate ddname MSOPROF to that library.

If you use other FOCUS Interfaces in addition to the IMS Interface, you must allocate additional datasets (such as load libraries, Access File libraries, and error datasets) specific to those Interfaces. For more information, see the FOCUS for IBM Mainframe Multi-Session Option Installation and Technical Reference Guide.

To connect to the DBCTL environment after the MSO server is running, see the next section.



x
Console Commands for Controlling the DBCTL Environment

The system administrator can use the MSO or MVS operator's console to start and stop the DBCTL thread, modify the security class, and change the DFSPZPxx module that is loaded at initialization time.

The following commands can be issued from the console

/[F jobname,]IMSPZP=xx
/[F jobname,]DBCTL= START
/[F jobname,]DBCTL= STOP[,I]   
/[F jobname,]IMSSEC= {ON|OFF}
/[F jobname,]IMSCLASS=classname 
/[F jobname,]DBCTL ?

where:

/

Is required syntax.

F jobname,

Is syntax for issuing a command from the MVS operator's console.

xx

Sets the name of the DRA Startup Table (see Create the DRA Startup Table: DFSPZPxx). Must be issued prior to the /DBCTL=START command.

START

Starts the DBCTL connection to IMS.

STOP

Stops the DBCTL connection to IMS after waiting for all currently-executing requests to finish.

STOP,I

Stops the DBCTL connection to IMS immediately; does not wait for requests to finish.

ON

Enables security checking as described in Security.

OFF

Disables security checking as described in Security.

classname

Is a valid class that contains security authorization information. See Security.

?

Displays current DBCTL settings.

Note: If you issue the DISPLAY USER (DU) command from the MSO console, a new column (PSB) displays the name of the active PSB.

For more information about the MSO console, consult the FOCUS for IBM Mainframe Multi-Session Option Installation and Technical Reference Guide.



x
Shutting Down IMS in the DBCTL Environment

If the system operator shuts IMS down, the Interface terminates all active DBCTL threads immediately.

The proper way to shut down DBCTL consists of the following steps:

  1. Determine whether any active requests are running.
    • If no active requests are running, issue the /DBCTL STOP console command.
    • If active requests are running, issue the /DBCTL STOP,I console command.
  2. If you are running MSO, shut down the MSO server. If you are in TSO, exit from FOCUS.

Information Builders