In this section: |
This section describes steps for preparing the IMS DBCTL and XMI Server environments.
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:
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:
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.
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:
Is the IMS version number.
Is the output library where the PZP module (DRA Startup Table) will be stored.
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.
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 |
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.
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:
Is a PSB name to be protected by RACF.
Is the user ID of the system administrator.
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.
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:
The following chart lists the most common parameters:
Parameter |
Value |
Definition |
---|---|---|
MODE |
BMP |
Batch Message Processing mode. This mode accesses online IMS databases through the IMS/DC address space. See How to Initiate the XMI Server in BMP Mode. |
DLI |
Local mode. This mode accesses IMS databases that you allocate locally. See How to Initiate the XMI Server in DLI Mode. | |
Program |
XMI |
Loads and access the XMI server in the region controller address space. |
PSB |
psbname |
Identifies the PSB to use. |
One XMI server can service multiple users, but each user must have a separate PCB. Therefore, to allow multiple users, the PSB for the server should contain duplicate PCBs.
The job class and time expiration parameters used with the XMI server job must allow for a long residence in the system, and the priority should be sufficiently high to give good response to the users being serviced. In setting the various job parameters that affect response, remember that these jobs spend most of their time in the WAIT state consuming no resources, since they have nothing to do when not responding to DL/I calls. Even when processing such calls, they only do minimal work. All the logical work of the adapter is done in the various adapter address spaces.
A successfully started XMI server job will not end automatically. It must be terminated by the server operator when you no longer require access to the IMS data sources.
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:
Is the name of the PSB to use.
Is the high-level qualifier of the server load library, HOME.LOAD (or P.HOME.LOAD for PDS deployment).
Is the PDS library with the FOCPSB member.
Note: The FOCPSB is described in How to Define a FOCPSB.
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.
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.
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:
Is the name of the PSB to use.
Is the high-level qualifier of the server load library, HOME.LOAD (or P.HOME.LOAD for PDS deployment).
Is the PDS library with the FOCPSB member.
Note: The FOCPSB is described in How to Define a FOCPSB.
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.
Is the location of the server configuration information.
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.
A successfully started XMI server job will not end automatically. It must be terminated in one of three ways:
Using the Web Console, create a new procedure containing the following commands and run the procedure to stop the XMI job
ENGINE IMS XMI KILL XMIIMS1 END
where:
Is the client node in the Reporting Server communication (ODIN) file.
WebFOCUS |