The "handshake" between the adapter, running in its address space (or as a batch job), and XMI, running in another address space, requires a communication file accessible to both. This file must be allocated to ddname FOCBMP. It consists of a single 16-byte record, and it plays no role in subsequent message traffic between the two programs. Space for this file must be allocated once (on a permanently mounted disk pack) and catalogued as part of the installation of the XMI server (see Installation Instructions). The data set name is irrelevant.

Note: The following discussion assumes that the FOCUS production libraries are stored in data sets catalogued under the same high-level qualifier. The identifier prefix denotes this common high-level qualifier.

After the communication file has been created, when you subsequently invoke the adapter and the XMI server, allocate this file as follows:

• In the JCL that initiates the XMI server:

  //FOCBMP DD DSN=prefix.FOCBMP.DATA,DISP=SHR

• In the FOCUS application:

  From	Allocation
  The CLIST that invokes FOCUS	ALLOC F(FOCBMP) DA('prefix.FOCBMP.DATA') SHR REUSE
  A FOCUS session	{MVS|TSO} ALLOC F(FOCBMP) DA('prefix.FOCBMP.DATA') SHR REU
  Batch FOCUS JCL	//FOCBMP DD DSN=prefix.FOCBMP.DATA,DISP=SHR or DYNAM ALLOC FILE FOCBMP DATASET prefix.FOCBMP.DATA SHR

//FOCBMP DD DSN=prefix.FOCBMP.DATA,DISP=SHR

//FOCBMP DD DSN=prefix.FOCBMP1.DATA,DISP=SHR

DYNAM ALLOC FILE FOCBMP  DA prefix.FOCBMP.DATA SHR
DYNAM ALLOC FILE FOCBMP1 DA prefix.FOCBMP1.DATA SHR

If none of the FOCBMP files are allocated, the adapter does not attempt to use the XMI server. It issues its own DL/I calls instead. These DL/I calls will be successfully transmitted to IMS only if your environment is configured as described in Access to IMS With FOCUS Loaded by the Region Controller.

Since IMS uses the PCB to maintain the position of an application program in the database, concurrent users who are serviced by the same XMI job cannot share PCBs.

Each user application that accesses the server queries all the XMI jobs to which it is linked through the communication files, until it finds one that has a free PCB appropriate for reporting on the database. (The search for an available PCB is transparent to the user.) The PCB remains occupied for the duration of the retrieval portion of a request and is freed prior to the output portion of the request.

Thus, if ten users need concurrent access to the SALES database, the PSB must contain at least ten PCBs that correspond to the Master File for SALES. The eleventh user will receive a diagnostic message indicating that there is no free PCB available at the time. (In this case, the user should initiate another XMI server, as illustrated in previous sections.)

The ten SALES PCBs can reside in one of the following:

• In a single PSB that requires only one XMI job.
• In ten identical PSBs with one SALES PCB each for ten concurrent XMI jobs.
• In any other combination that adds up to ten.

The IMS DBA must determine which configuration is best for the site. The tradeoff is between a single large PSB that ties up only one XMI region or several XMI regions, each running a non-duplicated and, therefore, smaller PSB.

Note: If the PSB contains multiple PCBs for the same database, in order to allow access through secondary indexes, you must duplicate the whole block of PCBs. IMS Overview and Mapping Concepts and Creating FOCUS Descriptions describe secondary index PCBs.

A successfully started XMI server job will not end automatically. The operator must terminate it in one of three ways:

• By executing job XMIKILL, 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 XMI server is processing a DL/I call. The MVS cancel will also bypass the server 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 XMI server 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 XMIKILL avoids problems. The job sends the server a termination message that breaks into the server message queue ahead of all other messages addressed to it. Upon receipt of this message, the server performs its cleanup and returns to IMS, signaling a normal completion.

Sample JCL for job XMIKILL follows

//XMIKILL  EXEC PGM=FOCUS,REGION=nn 
//STEPLIB  DD DSN=prefix.FOCLIB.LOAD,DISP=SHR
//ERRORS   DD DSN=prefix.ERRORS.DATA,DISP=SHR
//SYSOUT   DD SYSOUT=*
//ddname   DD DSN=comfile,DISP=SHR
//FOCEXEC  DD DSN=prefix.FOCEXEC.DATA,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
EX XMI ACTION=STOP,GATEWAY=FOCBMP
FIN
/*
//

where:

nn

Is the region size.

prefix

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

ddname

Is the ddname allocated to the communication file of the XMI server job to be terminated. If only one job is to be terminated, use ddname FOCBMP.

comfile

Is the data set name of the communication file that is allocated to the XMI server job you want to terminate; for example, 'prefix.FOCBMP.DATA'.

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.