Accessing the BMP Extension

In the current FOCUS Release, the XMI server performs the function previously performed by the BMP extension (program FOCBMP). In order to access the BMP extension, you must SET IMS=OLD.

This is the required configuration for accessing IMS databases from CMS.

From the perspective of the end user, the only differences between using the XMI server and the BMP extension are the IMS setting and one parameter passed to the region controller program. Therefore, the explanations and diagrams that describe the XMI server in Environments, all pertain to the BMP extension. Consult that chapter for a complete explanation. This section provides an example that accesses the BMP extension.

The BMP extension is an application (program FOCBMP) that intercepts DL/I calls from the IMS/DB Interface address space and issues them to IMS. Before you can invoke the Interface with this configuration, there must be a BMP extension job executing with the appropriate parameter settings and with an available PCB for the databases you want to access.

Therefore, access to the BMP extension is a two-part process. The two parts consist of:

1. Initiating a BMP extension.

To initiate a BMP extension, you run a region controller program and pass it parameters that describe the environment you need. The following chart lists the most common parameters:

Parameters	Value	Definition
Mode	BMP	Indicates Batch Message Processing mode. This mode accesses online IMS databases through the IMS/DC address space.
	DLI	Indicates local mode. This mode accesses IMS databases that you allocate locally.
Program	FOCBMP	Loads and accesses the BMP extension in the region controller address space.
PSB	psbname	Identifies the PSB to use.

One BMP extension can service multiple users, but each user must have a separate PCB. Therefore, to allow multiple users, the PSB for the BMP extension should contain duplicate PCBs.

You may not have to actually execute this step because if a BMP extension is already running with the correct parameters and an available PCB, you can use it.

2. Invoking the Interface once a BMP extension job is running.

When you use the BMP extension to access IMS databases, you must allocate a common communication file (to ddname FOCBMP) in both the FOCUS address space and the BMP extension address space. See Environments, for a discussion of the communication file.

Example: Initiating a BMP Extension in DLI Mode

To initiate a BMP extension in DLI mode, 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.

You do not have to submit this JCL if a BMP extension job that has an available PCB is already running with the following parameter settings

//DLIXMI   EXEC PGM=DFSRRC00,REGION=nn,PARM='DLI,FOCBMP,psbname'
//STEPLIB    DD DSN=IMS.RESLIB,DISP=SHR
//           DD DSN=prefix.FOCLIB.LOAD,DISP=SHR
//           DD DSN=prefix.IMS.LOAD,DISP=SHR
//DFSRESLB   DD DSN=IMS.RESLIB,DISP=SHR
//IMS        DD DSN=IMS.PSBLIB,DISP=SHR
//           DD DSN=IMS.DBDLIB,DISP=SHR
//DFSVSAMP   DD DSN=IMS.DFSVSAMP(bufpool),DISP=SHR
//PATDB01    DD DSN=IMS.PATIENT.DB,DISP=SHR
//PATDBIX    DD DSN=IMS.PATIENT.IX,DISP=SHR
//PATDBIX1   DD DSN=IMS.PATIENT.IX1,DISP=SHR
//PATDBIX2   DD DSN=IMS.PATIENT.IX2,DISP=SHR
//PATDBIX3   DD DSN=IMS.PATIENT.IX3,DISP=SHR
//FOCBMP     DD DSN=prefix.FOCBMP.DATA,DISP=SHR
//FOCPSB     DD DSN=prefix.IMS.FOCPSB(psbname),DISP=SHR
//ERRORS     DD DSN=prefix.ERRORS.DATA,DISP=SHR
//SYSPRINT   DD SYSOUT=*
//

where:

nn

Is the region size.

psbname

Is the name of the PSB to use.

prefix

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

bufpool

Is the member that contains your VSAM buffer pool information.

Note:

• The ddnames allocated to the IMS databases are from the DD1 parameters in the relevant IMS DBDs. In the sample, the databases are the PATDB databases and indexes described in Sample File Descriptions.
• IMS.RESLIB is the IMS load library, IMS.DBDLIB is the IMS DBD library, and IMS.PSBLIB is the IMS PSB library.
• If you specify the parameter DBB instead of DLI on the EXEC card, you must include the ACB library in the allocation for ddname IMS. In addition, you must allocate a second dataset, IMS.ACBLIB, to ddname IMSACB.
• Ddname FOCBMP is allocated to the common communication file. You must allocate the same file when you invoke the Interface, as described in Environments.
• Most error conditions detected by the BMP extension are reflected back to the originating user, where they are issued to the terminal. The SYSPRINT file allocated in the BMP extension job will contain only global error messages pertaining to the BMP extension environment as a whole, such as open errors on ddname FOCBMP or FOCPSB.
• PCBs for the BMP extension are discussed in Environments.

Once the BMP extension job is executing, you can invoke the Interface from a CLIST or from batch JCL, as described in Invoking the Interface in the BMP Extension Environment.

Invoking the Interface in the BMP Extension Environment

To invoke the Interface as a batch job, submit the following sample JCL after editing it to conform to your site's standards and adding a JOB card

//FOCXMI   EXEC PGM=FOCUS,REGION=nn
//STEPLIB  DD DSN=prefix.FOCLIB.LOAD,DISP=SHR
//         DD DSN=prefix.IMS.LOAD,DISP=SHR
//         DD DSN=prefix.FUSELIB.LOAD,DISP=SHR
//ERRORS   DD DSN=prefix.ERRORS.DATA,DISP=SHR
//FOCBMP   DD DSN=prefix.FOCBMP.DATA,DISP=SHR
//FOCEXEC  DD DSN=prefix.FOCEXEC.DATA,DISP=SHR
//MASTER   DD DSN=prefix.MASTER.DATA,DISP=SHR
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
SET IMS=OLD
TABLE FILE ...
  .
  .
  .
END
FIN
/*
//

where:

nn

Is the region size.

prefix

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

Note:

• You must SET IMS=OLD in your FOCUS session, as shown in the sample.
• You can also invoke the Interface from a CLIST (see Environments).

Terminating a BMP Extension

A successfully started BMP extension job will not end without intervention; the operator must terminate it in one of three ways:

• By executing job FOCBMPKX, described in this section. This is the recommended termination method.
• Through an MVS cancel.

The MVS cancel should be avoided because of its potential impact on the IMS/DC region if the cancellation occurs while the BMP extension is processing a DL/I call. The MVS cancel will also bypass the BMP extension's own cleanup process with the result that a 4K area in the CSA (Common Storage Area) will not be freed and will remain unavailable until the next IPL.

• Through an IMS cancel.

The IMS cancel will properly disconnect the BMP extension and IMS/DC regions without any impact on the latter, but it will bypass the freeing of the 4K communication area in the CSA.

Termination through job FOCBMPKX avoids problems. The job sends the BMP extension a termination message that breaks into the server message queue ahead of all other messages addressed to it. Upon receipt of this message, the BMP extension performs its cleanup and returns to IMS, signaling a normal completion.

Execute job FOCBMPKX to terminate a BMP extension. Sample JCL for this job follows

//FOCBMPKX  EXEC PGM=FOCBMPKX,REGION=nn,PARM='ddname'
//STEPLIB  DD DSN=prefix.IMS.LOAD,DISP=SHR
//ddname   DD DSN=comfile,DISP=SHR

where:

nn

Is the region size.

prefix

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

ddname

Is allocated to the communication file of the BMP extension job to be canceled.

comfile

Is the dataset name of the communication file that is allocated to the BMP extension you want to terminate; for example, 'prefix.FOCBMP.DATA.'

Each execution of the FOCBMPKX job terminates one BMP extension job.

Any of the three termination methods can be invoked at any time, without impact on those who might be actively using the canceled job (except for the impact on IMS/DC discussed previously). All such users will receive one of several error messages, depending on where in their retrieval process the cancellation occurred. Their retrieval ends cleanly; in no case will the user ABEND or be left with a hung terminal.