Gateway RPC Interface

B Gateway RPC Interface

To execute a remote transaction program using the Oracle Database Gateway for APPC you must execute a PL/SQL program to call the gateway functions, using a remote procedural call (RPC). The gateway functions handle the initiation, data exchange and termination for the gateway conversation with the remote transaction program.

The Oracle Database Gateway for APPC includes a tool, PGAU, to generate the PL/SQL packages (TIPs) automatically, based on definitions you provide in the form of COBOL record layouts and PGDL (Procedural Gateway Definition Language).

The gateway functions are all executed through remote procedural calls (RPC). The functions are called from PL/SQL code as follows:

function@dblink(parm1,parm2,...,parmn);

Where Table B-1 describes the parameters in this syntax:

Table B-1 Gateway Functions

Item	Description
`function`	is the name of the function being called.
`dblink`	is the name of a predefined database link to the gateway server on the Windows system.
`parm1, parm2,parmn`	are the function-specific parameters described later in this appendix.

Calling a function in PL/SQL code with the @dblink notation following the function name is a remote procedural call.

PGAINIT and PGAINIT_SEC

PGAINIT and PGAINIT_SEC are remote procedural calls that initiate an APPC conversation with a specified transaction program. The difference between the two is that PGAINIT_SEC includes the added capability of being able to set the gateway conversation security user ID and password to values other than the current Oracle user ID and password. Upon successful completion of either function, the conversation is ready to send data to the remote transaction program.

Table B-2 presents the PGAINIT and PGAINIT_SEC parameters that are common in both procedures. It lists the type, datatype and description of each parameter:

Table B-2 Common PGAINIT and PGAINIT_SEC Parameters

Parameters	Type	Datatypes	Descriptions
`CONVID`	`OUT`	`RAW(12)`	For a gateway using SNA: Conversation identifier returned by the `PGAINIT` function to be used to identify the conversation to the `PGAXFER` and `PGATERM` functions. After `PGAINIT` is called, this variable must never be modified, or results will be unpredictable. For a gateway using TCP/IP: Socket file descriptor returned by the `PGAINIT` function to be used to identify the conversation to the `PGAXFER` and `PGATERM` functions. After `PGAINIT` is called, this variable must never be modified, or results will be unpredictable.
`TPNAME`	`IN`	`VARCHAR2(64)`	Transaction program name of the remote transaction program with which a conversation is to be established. For most OLTPs, the name must be the transaction name as defined to the OLTP. This name can be from `1` to `64` characters in length. Note: For TCP/IP support, the maximum size is 8 characters. For more information, refer to Appendix B, "Gateway Initialization Parameters for TCP/IP Communication Protocol" in the Oracle Database Gateway for APPC Installation and Configuration Guide for IBM AIX on POWER Systems (64-Bit), Linux x86-64, Oracle Solaris on SPARC (64-Bit), and HP-UX Itanium or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows.
`LUNAME`	`IN`	`VARCHAR2(17)`	For a gateway using SNA: the LU name of the OLTP under which the remote transaction program executes. This parameter is the fully-qualified LU name or alias and can be from 1 to 17 characters in length. For a gateway using TCP/IP: this parameter is not applicable.
`MODENAME`	`IN`	`VARCHAR2(8)`	For a gateway using SNA: Logmode entry name of the logmode table entry on the remote host, which defines the session characteristics for the APPC conversation. This name can be from 1 to 8 characters in length. For a gateway using TCP/IP: this parameter is not applicable.
`PROFNAME`	`IN`	`VARCHAR2(8)`	Profile name of the SNA Side Information profile which defines the conversation. This name can be from 1 to 8 characters in length. For a gateway using TCP/IP: this name represents a group of IMS transactions similar of similar TCP/IP and IMS Connect attributes.
`SYNCLEVEL`	`IN`	`CHAR(1)`	`SYNCLEVEL` for this conversation. This value must be either '0' or '1'. `SYNCLEVEL 0` indicates that the remote transaction program has no synchronization capabilities. `SYNCLEVEL 1` indicates that the remote transaction program is capable of responding to `CONFIRM` requests and is used to ensure data integrity when the remote transaction program is making updates to a database on the remote host.

Table B-3 lists the PGAINIT_SEC parameters which are specific to the procedure:

Table B-3 PGAINIT_SEC Parameters Specific to the Procedure

Parameter	Type	Datatype	Description
`USERID`	`IN`	`VARCHAR2(8)`	Conversation security user ID to be passed to the target OLTP. The value must be from 1 to 8 characters in length.
`PASSWORD`	`IN`	`VARCHAR2(8)`	Conversation security password to be passed to the target OLTP. The value must be from 1 to 8 characters in length.

For Gateways Using the SNA Protocol:

There is an interrelationship between PROFNAME and LUNAME/TPNAME/MODENAME. If PROFNAME is set to blanks or a null value, the LUNAME, TPNAME, and MODENAME parameters are all required to be non-blank values. If they are not all set to non-blank values, an exception is generated. However, if PROFNAME is set to a valid Side Information Profile name, the LUNAME, TPNAME, and MODENAME parameters can be null or blank, because the Side Information profile specifies all the information necessary to establish the conversation. In this case, any non-blank, non-null values specified for LUNAME, TPNAME, or MODENAME override values set in the Side Information profile.PROFNAME must be set and cannot be blank or null.

For Gateways Using the TCP/IP protocol:

PROFNAME and TPNAME must be set and cannot be blank or null.

PGAXFER

PGAXFER is called to transfer data to and from a remote transaction program on the gateway conversation initialized by PGAINIT. The function sends and/or receives data items based on the calling parameters.

Table B-4 lists the types, datatypes and descriptions of PGAXFER parameters:

Table B-4 PGAXFER Parameters

Parameter	Type	Datatype	Description
`CONVID`	`IN`	`RAW(12)`	For a gateway using SNA: Conversation identifier returned by the `PGAINIT` function to be used to identify the conversation. For a gateway using TCP/IP: Socket file descriptor returned by the `PGAINIT` function to be used to identify the conversation.
`SENDBUF`	`IN`	`RAW(32763)`	Buffer containing all the data items to be sent to the remote transaction program. The data items are sent as is, with no changes. Data items must appear in the buffer in the exact order in which the remote transaction program expects to receive them. The total size of all the data items cannot exceed the maximum size for a single gateway send, which is `32,763` bytes for a mapped gateway conversation.
`SENDBUFL`	`IN`	`BINARY_INTEGER`	Total length of the data items contained in `SENDBUF`. The range is `0`-`32,763` bytes. A value of '`0`' is used when there are no data items to send.
`SENDLNS`	`IN`	`RAW(1024)`	Buffer containing an array of up to `256` 4-byte integer values. The first integer value specifies the number of data items contained in the send buffer (`SENDBUF`). Following that data item count is a series of integer values specifying the lengths of the data items. There must be an exact match between the data item count and the number of data item length values. Up to `255` data items can be described by this array. The sum of all the data item lengths cannot exceed the total length in `SENDBUFL`.
`RECVBUF`	`OUT`	`RAW(32763)`	Buffer to contain all the data items received from the remote transaction program. The data items are stored in this buffer in the exact order in which the remote transaction program sends them. The total size of all the data items cannot exceed the maximum size of `32,763` bytes.
`RECVBUFL`	`IN`	`BINARY_INTEGER`	Total length of the receive buffer. The range is `0`-`32,763` bytes. A value of '`0`' is used when there are no data items to receive.
`RECVLNS`	`INOUT`	`RAW(1024)`	Buffer containing an array of up to `256` 4-byte integer values. The first integer value specifies the number of data items to be received into the receive buffer (`RECVBUF`). Following the data item count is a series of integer values specifying the maximum lengths of the data items to be received. On output, these values are replaced with the actual lengths of the data items received. There must be an exact match between the data item count and the number of data item length values. Up to `255` data items can be described by this array. The sum of all the data item lengths cannot exceed the total length of the receive buffer (`RECVBUFL`).

When PGAXFER is called, either or both of SENDBUFL and RECVBUFL must be nonzero; in other words, at least one data item must be sent to or received from the remote transaction program. If PGAXFER is called with no data items to send or receive, it generates an exception.

Note:

On each PGAXFER call, all send processing occurs first, followed by all receive processing. If a transaction operates in a manner that requires multiple sets of send and receives, then PGAXFER can be called more than once to accommodate the transaction. If more than 32,763 bytes of data are to be sent or received, multiple calls to PGAXFER must be made.

PGATERM

PGATERM is called to terminate an the gateway conversation that was initiated by a previous call to PGAINIT. Upon successful completion of this function, the conversation is deallocated and all storage associated with it is freed.

Table B-5 presents the types, datatypes and descriptions of PGATERM parameters:

Table B-5 PGATERM Parameters

Parameter Type Datatype Description

CONVID

IN

RAW(12)

For a gateway using SNA: Conversation identifier returned by the PGAINIT function to be used to identify the conversation.

For a gateway using TCP/IP: Socket file descriptor returned by the PGAINIT function to be used to identify the conversation.

TERMTYPE

IN

CHAR(1)

Type of termination to be performed.'0' indicates normal completion and '1' indicates abnormal termination, which is only requested if there is an error.

PGATCTL

PGATCTL is called by the TRACE_LEVEL parameter at %ORACLE_HOME%\dg4appc\admin\initsid.ora file for Microsoft or $ORACLE_HOME/dg4appc/admin/initsid.ora file on UNIX based systems. Using PGATCTL, the trace level can be changed dynamically from within a PL/SQL stored procedure. This facility is useful when debugging a new PL/SQL application.

Table B-6 presents the types, datatypes and descriptions of parameters in PGATCTL:

Table B-6 PGATCTL Parameters

Parameter Type Datatype Description

CONVID

IN

RAW(12)

For a gateway using SNA: Conversation identifier returned by the PGAINIT function to be used to identify the conversation.

For a gateway using TCP/IP: Socket file descriptor returned by the PGAINIT function to be used to identify the conversation.

TRFUNC

IN

CHAR(1)

Trace control function to be performed. The valid values are:

'S' - set trace flags to the exact value specified by the TRFLAGS parameter.

'E' - enable the trace flags specified by the TRFLAGS parameter, without changing any other flags.

'D' - disable the trace flags specified by the TRFLAGS parameter, without changing any other flags.

TRFLAGS

IN

BINARY_INTEGER

Trace flags.

Turn on TRACE_LEVEL. Refer to Appendix A, "Gateway Initialization Parameters for SNA Protocol" in the Oracle Database Gateway for APPC Installation and Configuration Guide for IBM AIX on POWER Systems (64-Bit), Linux x86-64, Oracle Solaris on SPARC (64-Bit), and HP-UX Itanium or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows for more information if your protocol is SNA.

Refer to Appendix B, "Gateway Initialization Parameters for TCP/IP Communication Protocol" in the Oracle Database Gateway for APPC Installation and Configuration Guide for IBM AIX on POWER Systems (64-Bit), Linux x86-64, Oracle Solaris on SPARC (64-Bit), and HP-UX Itanium or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows.

PGATRAC

This function is called to write a line of user data into the PGA trace file. Using PGATRAC, the flow within a PL/SQL procedure can be traced, along with the events traced, based on the TRACE_LEVEL at %ORACLE_HOME%\dg4appc\admin\initsid.ora for Microsoft Windows or $ORACLE_HOME/dg4appc/admin/initsid.ora on UNIX based systems. This is a useful debugging tool when developing a new PL/SQL application.

Table B-7 presents the type, datatype and description of the PGATRAC parameter:

Table B-7 PGATRAC Parameter

Parameter	Type	Datatype	Description
`TRDATA`	`IN`	`VARCHAR2(120)`	Line of user data to be written into the gateway trace file. The contents must be printable characters.