Preparing the IMS Environment

In this section:

This section describes steps for preparing the IMS DBCTL and XMI Server environments.


Top of page

x
Preparing the IMS DBCTL Environment

In this section:

How to:

Reference:

Before configuring the Adapter for IMS verify that your site is running an IBM-supported version of IMS and that 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 rerun the IMS SYSGEN to make the changes effective.

The Adapter for IMS connects using the DBCTL environment. For the connection to be made, the following libraries must be identified and allocated to the STEPLIB in the IRUNJCL JCL member of your server configuration file:

Note: For example, for PDS deployment, the server configuration file is of the form qualif.release.server_type.DATA where qualif is provided by the user. The release and server_type vary with the release and license key being used. Refer to the Server Installation for z/OS in the Server Installation manual for further information on the configuration data set naming convention.

The PZP library must have a member that has been generated to identify the correct DBCTL environment for the connection. The following steps must be completed before the server can be configured, using the Web Console or Data Management Console, for the Adapter for IMS:

  1. How to Create the DRA Startup Table: DFSPZPxx
  2. Assembling and Linking the DRA Startup Table
  3. Establishing Security


x
Syntax: How to Create the DRA Startup Table: DFSPZPxx

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 name of the DRA Startup Table is

DFSPZPxx

where:

xx

Is a two-character suffix that should be chosen to comply with your site standards.

Once this suffix has been chosen, its value is needed during the configuration phase using the Web Console or Data Management Console.



Example: Assembling and Linking the DRA Startup Table

This sample JCL illustrates how to assemble and link the DFSPZPxx member. You can normally find sample JCL in your IMS installation library.

//job card goes here
//ASSEMBLE EXEC  PGM=ASMA90,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=IMSx,                                           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=qualif.outputlib 

where:

x

Is the IMS version number.

qualif.outputlib

Is the output library where the PZP module (DRA Startup Table) will be stored.

xx

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

Note: The qualif.outputlib library must be concatenated ahead of IMS.RESLIB in the allocation for DDNAME STEPLIB in the IRUNJCL member of your server configuration file.



x
Reference: Keywords for Generating the DFSPZP Library

The following chart describes the keywords required to generate the DFSPZP library. Other keywords that affect your IMS environment, and may be required at your site, are described in the IBM IMS System Definition Reference.

Keyword

Description

Default

AGN

Is a 1 to 8 character application group name used as part of the DBCTL security function. For more information on DBCTL security, see the IMS System Administration Guide.

N/A

CNBA

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

N/A

DBCTLID

Is the 4-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 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

Is the 1- to 44-character data set name of the DBCTL RESLIB library. It must contain the DRA modules and be MVS authorized.

IMS.RESLIB
FPBOF

Is 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 System Administration Guide. You can omit this keyword if your site does not use Fast Path.

00

FPBUF

Is 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 System Administration Guide. You can omit this parameter if your site does not utilize Fast Path.

00

FUNCLV

Is 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

Is the maximum number of concurrent DRA threads. The value cannot exceed 255.

1

MINTHRD

Is the minimum number of concurrent DRA threads available. Since the number of threads specified by this keyword will be allocated at all times, regardless of whether they are used, be careful when selecting this value. The value cannot exceed 255.

1

SOD

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

A

TIMEOUT

Is 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

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

60

USERID

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

N/A



x
Establishing Security

The DBCTL environment, when accessed through the server, enables the use of security systems through the standard SAF interface. With the SAF interface, your site can use security products such as RACF, CA TOP SECRET, and CA ACF2 to restrict access to PSBs. Before allowing access to a particular PSB, the security system verifies that the user is authorized to read the PSB.

Note: The DBCTL function is tested and verified with the RACF product. Other SAF products using identical calls should perform properly when installed and verified by your site's security administrator.

RACF comes with several predefined security classes. Customer sites can use an existing class (such as PCICSPSB) or define a resource class specifically for DBCTL use.



x
Syntax: How to Define a PSB Resource

The following syntax illustrates how to define a PSB resource through a PCICSPSB profile to RACF, and how to grant users permission to access the resource.

RDEFINE PCICSPSB (psbname) UACC(NONE) NOTIFY(sys_admin_userid)
PERMIT psbname CLASS(PCICSPSB) ID(user_or_group [user_or_group ...])
ACCESS(READ)

where:

psbname

Is a PSB name to be protected by RACF.

sys_admin_userid

Is the user ID of the system administrator.

user_or_group

Authorizes the user IDs and/or user groups listed in the PERMIT command to read the specified PSB. Separate items in the list with blanks.

At run time, after the PSB is selected, but prior to scheduling it, the server issues a call to the security system and verifies that the user is authorized to read the PSB.


Top of page

x
Preparing the IMS XMI Server Environment

How to:

The XMI server is an application (program XMI) that intercepts DL/I calls from the IMS/DB adapter address space and issues them to IMS. Before you can invoke the adapter with this configuration, there must be an XMI server job executing with the appropriate parameter settings and with an available PCB for the databases you want to access. Therefore, in order to issue requests to the XMI server using the adapter, you must first initiate the XMI server and then invoke the adapter once the server is running. In addition, you must terminate the XMI server job manually when you are finished using it. Therefore, accessing the adapter in the XMI server environment requires the following steps:



x
Syntax: How to Initiate the XMI Server in BMP Mode

BMP (Batch Message Processing) mode accesses online IMS databases under the control of IMS/TM. Therefore, you can access Fast Path databases with this configuration, and, if a record is updated, you retrieve the updated version.

The following JCL can be used to start an XMI server in BMP mode:

//BMPXMI EXEC PGM=DFSRRC00,PARM='BMP,XMI,psbname'
//STEPLIB  DD  DISP=SHR,DSN=qualif.server 
//         DD  DISP=SHR,DSN=IMS.RESLIB
//FOCPSB   DD  DISP=SHR,DSN=qualif.FOCPSB(psbname)
//SYSOUT   DD  SYSOUT=*,DCB=BLKSIZE=133
//EDAPRINT DD SYSOUT=*
//EDAPARM  DD DUMMY
//EDACS3   DD DISP=SHR,DSN=qualif.yourdsn(XMIODIN)
//EDAENV   DD *
EDACS3=//DD:EDACS3
EDACONF=edaconflocation

where:

psbname

Is the name of the PSB to use.

qualif.server

Is the high-level qualifier of the server load library, HOME.LOAD (or P.HOME.LOAD for PDS deployment).

qualif.FOCPSB

Is the PDS library with the FOCPSB member.

Note: The FOCPSB is described in How to Define a FOCPSB.

qualif.yourdsn

Is the user-supplied library where the communication (ODIN) member is to be stored.

Note: The ODIN file is described in Configuring the Adapter for IMS in the XMI Server Environment.

edaconflocation

Is the location of the server configuration information.

Note: To get XMI traces, include -traceon in the EDAPARM control card. For USS, XMI traces will be located in the home directory. For PDS deployment, add XMITRACE=//DD:XMITRC in EDAENV and XMITRC DD name with DSN in the JCL.

Sample JCL is provided in member IIMSBMP of the server configuration library. Note that certain values will be automatically filled in for you.



x
Syntax: How to Initiate the XMI Server in DLI Mode

DLI mode accesses IMS databases that you allocate locally in the DFSRRC00 address space. Since you do not access the IMS/TM address space, you cannot use Fast Path databases and, if a record is updated during your session, you cannot retrieve the updated record.

Note: If you substitute the parameter DBB for DLI, IMS uses ACBs when accessing databases.

This ensures that the database is in sync with the IMS descriptions you are using.

To initiate an XMI server with this configuration, submit the following JCL after editing it to conform to your site's standards and adding a JOB card. Note that you must allocate your IMS databases, DBDs, and PSBs in this JCL.

//DLIXMI   EXEC PGM=DFSRRC00,PARM='DLI,XMI,psbname'
//STEPLIB  DD DISP=SHR,DSN=qualif.server 
//         DD DISP=SHR,DSN=IMS.RESLIB
//DFSRESLB DD DISP=SHR,DSN=IMS.RESLIB
//DFSVSAMP DD DISP=SHR,DSN=IMS.DSFVSAMP(member)
//IEFRDER  DD DUMMY
//FOCPSB   DD DISP=SHR,DSN=qualif.FOCPSB(psbname)
//IMS      DD DISP=SHR,DSN=IMS.DBDLIB
//         DD DISP=SHR,DSN=IMS.PSBLIB
//IMSDD DD DISP=SHR,DSN=qualif.IMSFILE
//IMSDDIX DD DISP=SHR,DSN=qualif.IMSFILE.INDEX
//SYSOUT  DD SYSOUT=*,DCB=BLKSIZE=133
//EDAPARM DD DUMMY
//EDACS3   DD DISP=SHR,DSN=qualif.yourdsn(XMIODIN)
//EDAENV   DD *
EDACS3=//DD:EDACS3
EDACONF=edaconflocation

where:

psbname

Is the name of the PSB to use.

qualif.server

Is the high-level qualifier of the server load library, HOME.LOAD (or P.HOME.LOAD for PDS deployment).

qualif.FOCPSB

Is the PDS library with the FOCPSB member.

Note: The FOCPSB is described in How to Define a FOCPSB.

qualif.yourdsn

Is the user-supplied library where the communication (ODIN) member is to be stored.

Note: The ODIN file is described in Configuring the Adapter for IMS in the XMI Server Environment.

edaconflocation

Is the location of the server configuration information.

IMS.DSFVSAMP(member)

Is the library member that contains your VSAM buffer pool information.

Note: To get XMI traces, include -traceon in EDAPARM control card. For USS, XMI traces will be located in the home directory. For PDS deployment, add XMITRACE=//DD:XMITRC in EDAENV and XMITRC DD name with DSN in the JCL.

Sample JCL is provided in member IIMSDLI of your server configuration file. Note that certain values will be automatically filled in for you.



x
Procedure: How to Terminate an XMI Server

A successfully started XMI server job will not end automatically. It must be terminated in one of three ways:


iWay Software