The client program

Step through the client program PRG001, in COBOL pseudocode, as it creates a server process and requests that it is run.

Figure 1. Example client program, PRG001 (Part 1)


Identification Division.
Program-id. PRG001.
Environment Division.
Data Division.
Working-Storage Section.
01 RC pic s9(8) comp.
01 Unique-Reference pic x(36) value low-values..
01 Process-Type pic x(8) value 'Servers'.
.
01 Event-Name pic x(16) value low-values..
01 Work-Buffer..
01 Work-request Pic x.
88 Work-New value 'N'.
88 Work-Continue value 'C'.
88 Work-End value 'E'.

Linkage Section.
01 DFHEIBLK..
01 DFHCOMMAREA...

Figure 2. Example client program, PRG001 (Part 2)


Procedure Division using DFHEIBLK DFHCOMMAREA.
In-The-Beginning..
EXEC CICS SEND ...
RESP(data-area) END-EXEC.
EXEC CICS RECEIVE ...
RESP(data-area) END-EXEC.
Move ..unique.. TO Unique-Reference
Move ..request.. TO Work-Request.
Evaluate True
When Work-New
Perform New-Process
When Work-Continue
Move 'SRV-WORK' TO Event-Name
Perform Existing-Process
When Work-End
Move 'SRV-SHUTDOWN' TO Event-Name
Perform Existing-Process
When Other.
End Evaluate..
EXEC CICS GET CONTAINER('Server-Out')
 ACQPROCESS INTO(Work-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC.
EXEC CICS SEND ...
RESP(data-area) END-EXEC.
EXEC CICS RETURN END-EXEC.
New-Process..
 EXEC CICS DEFINE PROCESS(Unique-Reference)
PROCESSTYPE(Process-Type)
TRANSID('SERV')
PROGRAM('SRV001')
RESP(data-area) RESP2(data-area) END-EXEC.
 EXEC CICS PUT CONTAINER('Server-In')
ACQPROCESS FROM(Work-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC.
 EXEC CICS RUN ACQPROCESS
SYNCHRONOUS
RESP(RC) RESP2(data-area) END-EXEC.

Figure 3. Example client program, PRG001 (Part 3)


Existing-Process..
 EXEC CICS ACQUIRE PROCESS(Unique-Reference)
PROCESSTYPE(Process-Type)
RESP(data-area) RESP2(data-area) END-EXEC.
 EXEC CICS PUT CONTAINER('Server-In')
ACQPROCESS FROM(Work-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC.
 EXEC CICS RUN ACQPROCESS
SYNCHRONOUS
INPUTEVENT(Event-Name)
RESP(RC) RESP2(data-area) END-EXEC.
End Program.

First, PRG001 determines if this is the first time the server is to be called. If it is, it establishes a unique name for this instance of the server process. Then it creates the server process by issuing a DEFINE PROCESS command with that unique name. PRG001 provides some input data for the server in a data-container named Server-In :

 EXEC CICS PUT CONTAINER('Server-In')
ACQPROCESS FROM(Work-Buffer)
RESP(data-area) RESP2(data-area) END-EXEC

The ACQPROCESS option associates the Server-In container with the process that PRG001 has “acquired”. A program “acquires” access to a process in one of two ways: either, as here, by defining it; or, if the process has already been defined, by issuing an ACQUIRE PROCESS command.

Having created the server process, PRG001 issues a request to run it synchronously. The RUN ACQPROCESS command causes the currently acquired process to be activated. Because RUN ACQPROCESS rather than LINK ACQPROCESS is used, the server process is run in a separate unit of work from that of the client. PRG001 waits for the server to run, and then retrieves any data returned from a data-container named Server-Out.

PRG001 has now temporarily finished using the server process; the implicit sync point at RETURN causes it to be released.

To use this instance of the server again, PRG001 must first acquire access to the correct process. It does this by issuing an ACQUIRE PROCESS command which specifies the unique combination of the name and process-type of the process:

 EXEC CICS ACQUIRE PROCESS(Unique-Reference)
PROCESSTYPE(Process-Type)
RESP(data-area) RESP2(data-area) END-EXEC

Once again, PRG001 provides input data for the server in a data-container named Server-In , and requests the process to be run:


 EXEC CICS RUN ACQPROCESS
SYNCHRONOUS
INPUTEVENT(Event-Name)
RESP(RC) RESP2(data-area) END-EXEC

PRG001 uses the INPUTEVENT option of the RUN command to tell the server why it has been invoked—in this case, it is for SRV-WORK. (The server must have defined an input event of that name.)

Again, PRG001 waits for the process to complete, retrieves any returned data, and releases the process.

Eventually, PRG001 tells the server to shut down by invoking it with an event of SRV-SHUTDOWN.