| Oracle Procedural Gateway® for APPC User's Guide 10g Release 2 (10.2) for UNIX Part Number B16210-01 |
|
|
View PDF |
| Oracle Procedural Gateway® for APPC User's Guide 10g Release 2 (10.2) for UNIX Part Number B16210-01 |
|
|
View PDF |
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 the gateway 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:
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 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 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 Chapter 12 of the Oracle Procedural Gateway for APPC Installation and Configuration Guide. |
| 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) | Sync level for this conversation. This value must be either '0' or '1'.
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 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 is called to transfer data to and from a remote transaction program on the gateway conversation initialized by PGAINIT. The function sends and 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 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 is called by the TRACE_LEVEL parameter at $ORACLE_HOME/pg4appc/admin/initsid.ora file. 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 Procedural Gateway for APPC Installation and Configuration Guide for more information if your protocol is SNA. Refer to Appendix B of the Oracle Procedural Gateway for APPC Installation and Configuration Guide if your protocol is TCP/IP. |
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/pg4appc/admin/initsid.ora. 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:
