5
Oracle Application Server Integration Adapter for IMS/TM Features

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

This chapter contains the following sections:

Sending Inbound Interactions Using an IMS/TM Transaction

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

See Also:

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

To send an inbound interaction, perform the following tasks:

Task 1: Setting Up the IBM OS/390 Machine

Before you can use the IMS/TM transaction, set it up using the following procedure:

Copy INSTROOT.LOAD(BASE) to an IMS/TM program library (such as IMS.PGMLIB).
Copy INSTROOT.LOAD(ATYDC3GL) to the same IMS/TM program library (such as IMS.PGMLIB).

Task 2: Setting Up a Call to the IMS/TM Transaction

The COBOL program sets up a buffer that contains the information needed for the inbound interaction and then calls the ATYDC3GL program 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 Oracle Connect for IMS/TM 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 ATYDC3GL transaction is called as follows:

Write the following lines of code:

*
*  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)


77 COMLEN PIC S9(4) COMP SYNC VALUE +5000. 
77 API-INTERFACE PIC X(8) VALUE 'ATYDC3GL'. 

CALL API-INTERFACE USING COMM-DATA-BUFF COMLEN.

where:

COMM-DATA-BUFF - The buffer with the interaction details.

COMLEN - 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.

The first time the CALL is performed, it will do a one-time fetch and a call. Thereafter, it will do only a call.

To release the module just before termination of the calling program, write the following line of code:
```
CANCEL API-INTERFACE.
```

After defining the buffer and calling the ATYDC3GL transaction in the COBOL program, compile and move the COBOL program to the IMS/TM program library (such as IMS.PGMLIB).

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.