Writing and Configuring a Natural Program

Reference:

To write and configure a Natural Program for use with the iWay Transaction Adapter for CICS:

  1. Write a Natural program to use the AASSUBC calls to send and receive data.

    For more information, see Using the AASSUBC Calling API and Natural Program.

  2. Using iWay Explorer, define a new CICS target with any supported communications type, for example, AnyNet, SNA, or TCP/IP.
  3. Click the Advanced tab after you have entered your connection parameters.

    The Advanced tab opens.

    Perform the following steps:

    1. Specify the name of the Natural Nucleus installed on the CICS region.
    2. Specify the Natural proxy program AASNATC.
    3. Specify the alternate mirror transaction in the CICS Mirror field.
    4. Adjust the default Natural Logon Parameters, as needed. The CICS adapter will automatically append a suitable STACK parameter to the end of Logon Parameters when each request is run, using the Natural library and the Program Name defined in the Service Node. A user may also include his own STACK= on the Logon Parameters and reference the Natural library and service program name via the strings #NATLIB and #NATPROG. For example: AUTO=OFF,TTYPE=ASYN,DBCLOSE=ON,ETID=OFF,IMSG=OFF,MENU=OFF,SENDER DUMMY,OUTDEST=DUMMY,ID=/,STACK=(LOGON #NATLIB;#NATPROG;FIN). In this case, the automatic STACK parameter is not appended.

      For more information on Natural Logon Parameters themselves, see the Natural documentation.

      Note: Since this target invokes the Natural proxy program, it is not suitable for use with non-Natural, ECI CICS programs.

  4. Connect to your CICS target, right-click the Transactions node, and select Add Service to create a service node that represents the Natural program.

    The Add Service window opens.

    Perform the following steps:

    1. Specify a name for the service node in the Node Name field.
    2. Specify the name of the Natural program to run in the Program Name field.
    3. Specify the library within the Natural subsystem where the program is stored in the Natural Library field.

      Note: This value is usually SYSTEM by default.

    4. Specify a COMMAREA size for the service to be a maximum of:

      The size of data sent to the Natural program + 300 and the maximum number of bytes to be received from the Natural program.

      The iWay Transaction Adapter for CICS requires this extra space on output to send the data required by the proxy program to invoke the Natural Nucleus.

    Note: This value is usually SYSTEM by default.

    The size of data sent to the Natural program + 300 and the maximum number of bytes to be received from the Natural program.

    The iWay Transaction Adapter for CICS requires this extra space on output to send the data required by the proxy program to invoke the Natural Nucleus.

For more information on Natural logon parameters, see the Natural documentation.

Note: This value is usually SYSTEM by default.

The size of data sent to the Natural program + 300 and the maximum number of bytes to be received from the Natural program.

The iWay Transaction Adapter for CICS requires this extra space on output to send the data required by the proxy program to invoke the Natural Nucleus.
Top of page
x
Reference: Using the AASSUBC Calling API

A Natural program must use program AASSUBC for all access to input and output buffers.

Calls to AASSUBC all use the following control block as their first parameter:

1 #REQUEST-PARMS
2 #FUNCTION      (A2)  GT,PT,LC,LI
2 #OFFSET        (I2)  DATA OFFSET OF INPUT/OUTPUT
2 #LENGTH        (I2)  LENGTH OF DATA TO GET OR PUT
2 #RESPONSE-CODE (I4)
2 #ERR-MESSAGE   (A72)

The following table lists and describes the implemented functions:

Function

Description

GT

Get input by offset.

The offset must be set to 0 for the first call only. It is incremented following each call by the number of bytes read.

The length of the requested data must be provided for each call and must match the length of the area provided to receive the input data. For example:

MOVE #FUNC-GT TO #FUNCTION
MOVE 8 TO #LENGTH 
MOVE 0 TO OFFSET  -  FIRST CALL ONLY
CALL 'AASSUBC' #FUNCTION #EMP-NUM1
WHERE #EMP-NUM1 IS AN EIGHT BYTE FIELD

PT

Put output by offset.

The offset must be set to 0 for the first call only. It is incremented following each call by the number of bytes written.

The length of the requested data must be provided for each call and must match the length of the area provided containing the output data. For example:

MOVE #FUNC-PT TO #FUNCTION
MOVE 8 TO #LENGTH 
MOVE 0 TO OFFSET  -  FIRST CALL ONLY
CALL 'AASSUBC' #FUNCTION #EMP-NUM1
WHERE #EMP-NUM1 IS AN EIGHT BYTE FIELD

LI

Get length of input data.

This function updates the #LENGTH field with the total length of all input parameters. No additional parameters are required. For example:

MOVE #FUNC-LI TO #FUNCTION
CALL 'AASSUBC' #FUNCTION

LC

Get length of COMMAREA used to send data.

This function updates the #LENGTH field with the COMMAREA length. No additional parameters are required. For example:

MOVE #FUNC-LC TO #FUNCTION
CALL 'AASSUBC' #FUNCTION

The following table lists and describes the implemented response codes:

Response Code

Description

0

Operation completed successfully.

4

ENDDATA - OFFSET exceeds end of input data and indicates that no further input is available.

8

OFFSET + LENGTH is greater than COMMAREA.

Note: Always use the first field of a group when calling AASSUBC. Notice all calls are made with #FUNCTION and not #REQUEST-PARMS.

All input fields must be read before output fields are written. The sample program aasnatn.natural shows how AASSUBC is used. On Windows, the Natural sample program is located in:

C:\Program Files\iWay60\etc\samples\cics\natural

For more information on using this program, see Natural Program.

iWay Software