5
Oracle Application Server Integration Adapter for CICS Features

After the Oracle Application Server Integration Adapter for CICS is installed and the modeling described in Chapter 3, "Modeling Interactions for Oracle Application Server Integration Adapter for CICS" and Chapter 4, "Using Interactions in a Business Process" completed, you can use the Oracle Application Server Integration Adapter for CICS to invoke interactions that access programs under CICS.

This chapter contains the following sections:

Sending Inbound Interactions Using a CICS Transaction

The Oracle Application Server Integration Adapter for CICS includes a set of APIs that enable sending a native event as an inbound interaction from a COBOL program, using a CICS transaction.

See Also:

Appendix D, "COBOL APIs to Applications" for details of APIs that can be used when not working under CICS

To send an inbound interaction, perform the following tasks:

Task 1: Setting Up the IBM OS/390 Machine

Before you can use the CICS transaction, set it up using the following procedure:

Copy INSTROOT.LOAD(ATTCICSD) to a CICS DFHRPL library.

Copy INSTROOT.LOAD(TRANS3GL) to a CICS DFHRPL library.

Note:

Make sure that the CICS Socket Interface is enabled. You can enable this interface by issuing the following CICS command:

EZAO START CICS

Refer to the TCP/IP V3R2 For MVS: CICS Sockets Interface Guide. If you are not sure if the system is configured with the Socket Interface, try running the EZAC transaction. If the transaction produces a screen, you should be able to run the EZAO startup transaction. If not, see if the transaction has been defined in a group that has not been installed, for example: CEDC V TRANS(EZAC) G(*).

If it is defined in a group, install that group and try running EZAO again. If not, you have to configure CICS as outlined in the TCP/IP V3R2 For MVS: CICS Sockets Interface Guide.

Set up CICS resource definitions for the COBOL program from which you want to send a native event as an inbound interaction.

The following JCL can be used as a template:

//ATTCSD  JOB  'ORACLE','CSD',MSGLEVEL=1,NOTIFY=&SYSUID
//STEP1   EXEC PGM=DFHCSDUP,REGION=512K,
//          PARM='CSD(READWRITE),PAGESIZE(60),NOCOMPAT'
//STEPLIB  DD  DSN=<HLQ1>.SDFHLOAD,DISP=SHR
//DFHCSD   DD  UNIT=SYSDA,DISP=SHR,DSN=<HLQ2>.CSD
//OUTDD    DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
*/********************************************************************/
*/*  ORACLE CICS Definitions                                  */
*/*                                                                  */
*/********************************************************************/
*---------------------------------------------------------------------*
* Note: Install GROUP(ORA) - CEDA IN G(ORA)                    *
*     If you are rerunning this, uncomment the DELETE command. *
*---------------------------------------------------------------------*
*
* Start ORACLE RESOURCES:
*
* DELETE                   GROUP(ORA)
  DEFINE PROGRAM(ATTCICSD) GROUP(ORA) LANGUAGE(C) DATALOCATION(ANY)
         DE(Oracle DLL)
  DEFINE PROGRAM(TRANS3GL) GROUP(ORA) LANGUAGE(C) DATALOCATION(ANY)
         DE(Oracle DLL)
  DEFINE PROGRAM(<PROG>) GROUP(ORA) LANGUAGE(<LANG>) DATALOCATION(ANY)
         DE(Oracle)
  DEFINE TRANSACTION(<ORATRAN>) GROUP(ORA) PROGRAM(<PROG>)
         TASKDATAL(ANY)
         DE(Oracle TRAN ID)
  LIST                     GROUP(ORA)
*
* End   ORACLE RESOURCES
*
/*
//

Make the following changes before running the JCL:

Modify the JCL, as follows:
- Change the JOB card to suit the site.
- Change <HLQ1> to point to the CICS SDFHLOAD library.
- Change <HLQ2> to point to the CICS CSD dataset.
- Change <LANG> to the LE370 for COBOL.
- Change <PROG> to the COBOL program name.
- If you are calling the COBOL program from a CICS transaction, change <ORATRAN> to the CICS transaction name that calls the COBOL program.
From CICS, install the ORA group, by issuing the following command:
```
CEDA IN G(ORA)
```

Task 2: Setting Up a Call to the CICS Transaction

The COBOL program sets up a buffer in the CICS COMMAREA that contains the information needed for the inbound interaction and then calls the TRANS3GL transaction to send the interaction.

The buffer is formatted as follows:

Parameter	Size	Description
Version	4	The version of the APIs used. The expected value is 1
ServersUrl	256	The URL of the OS/390 machine and the port number where the Oracle Connect for CICS backend adapter runs. For example, IP1:2552, where IP1 is the URL and 2552 is the port
Username	64	A valid username to access the OS/390 machine
Password	64	A valid password for the user name
Workspace	64	A daemon workspace. The default is Navigator
AdapterName	64	The name of the adapter defined in Oracle Studio
SchemaFileName	256	For future use. Leave blank
EncKeyName	64	For future use. Leave blank
EncKeyValue	256	For future use. Leave blank
InteractionName	64	The name of the interaction as defined in Oracle Studio
Flags	4	The following flags are available: 1 - A trace of the XML is performed 2 - A trace of the communication calls is performed 3 - Both the XML and communication calls are traced 4 - The NAT firewall protocol is used, with a fixed address for the daemon 5 - A trace of the XML is performed and the NAT firewall protocol is used, with a fixed address for the daemon 6 - A trace of the communication calls is performed and the NAT firewall protocol is used, with a fixed address for the daemon 7 - Both the XML and communication calls are traced and the NAT firewall protocol is used, with a fixed address for the daemon
Input format	4	The following formats are available: 0 - Input is provided as XML 1 - Input is provided using parameters
Input	-	The size of the input depends on the value specified in the `Input size` parameter If the Input format is set to `0` (XML), the input is formatted as follows: The first four bytes specify the size of the input XML string The next 64 bytes specifies the name of the record used for the output (the inbound interaction) The next bytes (to the exact length specified in the first four bytes) specify the input XML string. For example: `<findorder ORDER_NO='17' />` where `findorder` is the inbound interaction name If the Input format is set to `1` (the input is done using parameters), the input is formatted as follows: The first four bytes specify the number of parameters The next 4 bytes specify the maximum size of any parameter value The next 64 bytes specify the name of the record used for the output (the inbound interaction) The next 32 bytes specify the name of the parameter The next bytes (to the exact length specified in the first four bytes) specify the input parameter The following bytes repeat the last two entries until all the parameters are specified

The buffer is defined as follows:

*
*  COBOL COPY OF DATA BUFFER
*
01  COMM-DATA-BUFF  PIC X(5000).

01  COMM-DATA-BUFF-ERROR REDEFINES COMM-DATA-BUFF.
    05  COMM-ERROR-STATUS  PIC S9(8) COMP SYNC.
    05  COMM-ERROR-MSG     PIC X(256).

01  COMM-DATA-BUFF-INPUT REDEFINES COMM-DATA-BUFF.

    05  INPUT-COMMAREA-3GL.
        10   INCOM-VERSION           PIC S9(8) COMP SYNC.
        10   INCOM-SERVERS-URLS      PIC X(256).
*                      /* IP1:PORT[,IP2:PORT] [,...] */
        10   INCOM-USER-NAME         PIC X(64).
        10   INCOM-PASSWORD          PIC X(64).
        10   INCOM-WORKSPACE         PIC X(64).
        10   INCOM-ADAPTER-NAME      PIC X(64).
        10   INCOM-SCHEMA-FILE-NAME  PIC X(256).
        10   INCOM-ENC-KEY-NAME      PIC X(64).
        10   INCOM-ENC-KEY-VALUE     PIC X(256).
        10   INCOM-INTERACTION-NAME  PIC X(64).
        10   INCOM-DW-FLAGS          PIC S9(8) COMP SYNC.
        10   INCOM-INP-FORMAT        PIC S9(8) COMP SYNC.
        10   INCOM-EXEC-INPUT.
             15  INCOM-XML-BUFF.
                 20   INCOM-XML-ILEN  PIC S9(8) COMP SYNC.
                 20   INCOM-XML-INTER-OUTREC-NAME
                                             PIC X(64).
*     ====>>> CHANGE ??? TO LEN SPECIFIED IN INCOM-XML-ILEN
                 20   INCOM-XML-INPUT PIC X(???).
             15  INCOM-PARAM-BUFF REDEFINES INCOM-XML-BUFF.
                 20  INCOM-PARAM-COUNT     PIC S9(8) COMP SYNC.
                 20  INCOM-PARAM-VALUE-LEN PIC S9(8) COMP SYNC.
                 20  INCOM-PARAM-INT-OUTREC-NAME     PIC X(64).
*     ====>>> CHANGE ??  TO COUNT SPECIFIED IN INCOM-PARAM-COUNT
                 20  INCOM-PARAM-NAME-VALUE OCCURS ?? TIMES.
                     25  INCOM-PARAM-NAME    PIC X(32).
*     ====>>> CHANGE ?? TO LEN SPECIFIED IN INCOM-PARAM-VALUE-LEN
                     25  INCOM-PARAM-VALUE   PIC X(??).

01  COMM-DATA-BUFF-OUTPUT REDEFINES COMM-DATA-BUFF.

    05  COMM-OUT-STATUS   PIC S9(8) COMP SYNC.
    05  COMM-OUT-LENGTH   PIC S9(8) COMP SYNC.

    05  COMM-OUT-DATA     PIC X(4992)

The TRAN3GL transaction is called as follows:

EXEC CICS LINK PROGRAM("TRANS3GL")
             COMMAREA(commDataBuff)
             LENGTH(iCommSize);

where:

commDataBuff - The buffer with the interaction details, used in the COMMAREA.

iCommSize - The size of the buffer. This value is also used to determine the size of the output string. Thus make sure the value is big enough for the expected output.

After defining the COMMAREA and calling the TRAN3GL transaction in the COBOL program, compile and move the COBOL program to a CICS DFHRPL (LOAD) library.

The output includes a 4 byte success flag: Zero for success, otherwise failure. The output overrides the input. If the result is failure, an error message with a length of 256 bytes is returned.

If XML was specified for the input and the result is success, the output is formatted as XML, as follows:

The first four bytes specify the size of the output
The following bytes make up the XML output

If parameters were specified for the input and the result is success, the output is formatted as follows:

The first four bytes specify the size of the output
The next 32 bytes specify the name of the output attribute
The next bytes (to the exact length specified for the input string in the) specify the output value
The following bytes repeat the last two entries until all the output is specified

High Availability with Oracle Connect

You can configure a pool of server processes so that a server process is always available for a client request.