CICS ESS Customization

The IBM® Connect:Direct® CICS interface enables you to use IBM Connect:Direct through the Customer Information Control System (CICS) from local and remote sites. The system includes a set of nested menus, prompts for required information, online Help facilities, and monitoring features for current status.

In addition to the IBM Connect:Direct IUI, a facility is provided that enables you to issue standard IBM Connect:Direct commands from a CICS application program. You can use this interface for both terminal and non-terminal tasks. Following are two typical uses for this API:

  • For terminal tasks, the API enables an installer to provide their own user interface to all or part of IBM Connect:Direct or work with IBM Connect:Direct from application programs using the DGAN transaction.
  • For non-terminal tasks, the API enables an installer to write background transactions which programmatically issue IBM Connect:Direct commands. The most typical sequence is SIGNON - SUBMIT - SIGNOFF. In this case, the SIGNON generates a SIGNON TYPE=CICS, and the SIGNOFF results in a cleanup operation of the signon table entry, temporary storage, and so forth.

    To avoid having to sign on before each command and sign off after each command, the user application can pass a logical task number through the Q012TASK field. If Q012TASK is used, a user program can sign on once and issue multiple commands in pseudo-conversational mode. A signoff is only needed when the user application is terminating.

An example of the use of this facility is provided in member DGAQ247 of the $CD.SDGASAMP. This program enables you to type IBM Connect:Direct commands on a screen and view the resulting return code, message number, message text, and Process number assigned to your IBM Connect:Direct Process. In addition, the CICS application displays the name of the CICS Temporary Storage (TS) queue where the results of your command are stored, the count of items in the queue, and the maximum record length in the queue.

You must install both IBM Connect:Direct and the IBM Connect:Direct CICS interface, and they must be operating for the IBM Connect:Direct CICS API to function.

The following elements are required to use DGAQ247:

Component Description
DGAQ247 The program source, written in assembly language
DGAQM98 The BMS map used by DGAQ247
DGAQBMST A parsing macro used by DGAQ247
DGAQCA12 A command-level COMMAREA passed to the CICS Interface

Following is a sample IBM Connect:Direct API DRIVER screen. It shows data after the ESS registration program has signed on to the IBM Connect:Direct CICS API driver and issued an EVENT SERVICES CREATE command.

                           CONNECT:Direct API DRIVER
 COMMAND        EVENT SERVICES CREATE ID=MESOO031 WHERE(MAXQCNT=998 LASTSEQ=1
                STARTT=(02.14.2010,04:14:12.45) STOPT=(12.31.2041,24:00:00.00)
                TYPE=(QE,QW,QH,QT,PI,CE,CT,PT,CI,RJ,RT,JI,TI,SW,DP) )
 COMMAND RC     0000
 COMMAND MSG ID SOPM000I
 COMMAND MSG    An EVENT REQUEST HAS COMPLETED NORMALLY
 PROCESS NUMBER
 TD EXIT COUNT
 TS QUEUE NAME
 TS MAX LRECL
 EVENT RESTART DATA
 WHERE(STARTT=(00000,00:00:00.00),LASTSEQ=000)
 PF keys:  3 Exit   5 Signon   6 Command   7 Signoff

The following table describes the Driver fields:

Field Description
COMMAND This 3-line field contains your API command.
COMMAND RC This 4-character field contains the return code from your API Process.
COMMAND MSG ID This 8-character field contains the identification number of the message associated with your API Process.
COMMAND MSG This 64-character field contains the text of the message.
PROCESS NUMBER This 6-character field contains the Process number assigned by the system to your API Process.
TD EXIT COUNT This 6-character field contains the number of bytes indicating how much data is written by the exit module for your API Process.
TS QUEUE NAME This 8-character field contains the name of the TS queue used during your API request.
TS MAX LRECL This 4-character field contains the maximum logical record length in bytes of the TS queue.
EVENT RESTART DATA This 62-character field contains the DATE/TIME/SEQ of the last event record successfully received. Data is only displayed if an EVENT SERVICES CREATE command is issued and a previous event services request had ended abnormally.