Skip Headers

Oracle® Procedural Gateway for APPC User's Guide
Release 9.2.0.1.0 for UNIX

Part Number A96649-01
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

C
Gateway RPC Interface

To execute a remote transaction program using the Oracle Procedural 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 an APPC conversation with the remote transaction program. The Oracle Procedural 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).

This appendix contains the following section:

Calling Gateway Functions to Execute Transaction Programs

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:

function is the name of the function being called.

dblink is the name of a predefined database link to the gateway server on the UNIX 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 also includes the added capability of being able to set the APPC 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.

The following table presents the parameters that are passed to both PGAINIT and PGAINIT_SEC. It lists the type, datatype and description of each parameter:

Parameter Type Datatype Description

CONVID

OUT

RAW(12)

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.

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.

LUNAME

IN

VARCHAR2(17)

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.

MODENAME

IN

VARCHAR2(8)

Logmode entry name of the logmode table entry on the remote system which defines the session characteristics for the APPC conversation. This name can be from 1 to 8 characters in length.

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.

SYNCLEVEL

IN

CHAR(1)

Sync level for this conversation. This value must be either '0', '1', or '2'.

Sync level 0 indicates that the remote transaction program has no synchronization capabilities.

Sync level 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 system.

Sync level 2 indicates that the remote transaction program is capable of responding to SYNC requests and is used to implement two-phase commit. Only one sync level 1 or 2 conversation can be active at any time from a single gateway session.

Note that not all platforms support sync level 2 with the gateway. Refer to the Oracle Procedural Gateway for APPC Installation and Configuration Guide for your platform for information on whether or not your platform supports sync level 2.

The following table lists the types, datatypes and descriptions of additional parameters which are passed only to PGAINIT_SEC:

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.

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.

PGAXFER

PGAXFER is called to transfer data to and from a remote transaction program on an APPC conversation initialized by PGAINIT. The function sends and/or receives data items based on the calling parameters. The following table list the types, datatypes and descriptions of parameters that are passed to PGAXFER:

Parameter Type Datatype Description

CONVID

IN

RAW(12)

Conversation identifier 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 APPC send, which is 32,763 bytes for a mapped APPC 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 for a single APPC receive, which is 32,763 bytes for a mapped APPC conversation.

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 APPC 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. The following table presents the types, datatypes and descriptions of PGATERM parameters:

Parameter Type Datatype Description

CONVID

IN

RAW(12)

Conversation identifier 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 to manipulate the PGA trace control flags. These are the same flags set at gateway initialization time by the SET TRACE_LEVEL PGA parameter. 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.

The following table presents the types, datatypes and descriptions of parameters in PGATCTL:

Parameter Type Datatype Description

CONVID

IN

RAW(12)

Conversation identifier returned by the PGAINIT function to be used to identify the conversation. If this parameter is set to binary zeroes, the new trace settings affect only conversations started after this call to PGATCTL. If this parameter is set to binary ones, the new trace settings affect all currently active conversations. Otherwise, the new trace settings affect only the specified 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. For valid values, refer to the discussion of the SET TRACE_LEVEL parameter in Appendix A of the Oracle Procedural Gateway for APPC Installation and Configuration Guide for your platform.

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 SET TRACE_LEVEL settings. This is a useful debugging tool when developing a new PL/SQL application.

The following table presents the type, dataype and description of the 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.


Go to previous page Go to next page
Oracle
Copyright © 1996, 2002 Oracle Corporation.

All Rights Reserved.
Go To Table Of Contents
Contents
Go To Index
Index