Release 9.0.1.0.1 for UNIX
Part Number A90397-01
 Library |
 Product |
 Contents |
 Index |
| Oracle Procedural Gateway for APPC User's Guide Release 9.0.1.0.1 for UNIX Part Number A90397-01 |
|
The PGAU generates complete and operational TIPs for most circumstances. TIP internals information is provided to assist you in diagnosing problems with PGAU-generated TIPs, and in writing custom TIPs, if you choose to do so.
This appendix refers to a sample called pgadb2i. The source for this TIP is in file pgadb2i.sql in the $ORACLE_HOME/pg4appc/demo/CICS directory.
This appendix contains the following sections:
Several topics are important to understanding TIP operation and development; following is a list of concepts that are key to TIP operation and suggested sources to which you can refer for more information.
PGAU GENERATE writes each output TIP into a standard PL/SQL package specification file and body file. This separation is beneficial and important. Refer to the Oracle9i Application Developer's Guide and the PL/SQL User's Guide and Reference for more information. Also refer to "GENERATE" in Chapter 2, "Procedural Gateway Administration Utility" for more information about building the PL/SQL package.
TIPs are PL/SQL packages. Any time a package specification is recompiled, all objects which depend on that package are invalidated and implicitly recompiled as they are referenced, even if the specification did not change.
Objects which depend on a TIP specification include client applications that call the TIP to interact with remote host transactions.
It might be important to change the TIP body for the following reasons:
Provided that the TIP specification does not need to change or be recompiled, the TIP body can be regenerated and recompiled to pick up changes without causing invalidation and implicit recompilation of client applications that call the TIP.
It is for this reason that PGAU now separates output TIPs into specification and body files. Refer to "GENERATE" in Chapter 2, "Procedural Gateway Administration Utility" for a discussion of file identification.
Independent TIP body changes are internal and require no change to the TIP specification. Examples of such changes include: a change in UTL_RAW or UTL_PG conversions, inclusion of diagnostics, or a change to network transaction parameters.
In these cases, when PGAU is used to regenerate the TIP, the new TIP specification file can be saved or discarded, but should not be recompiled. The new TIP body should be recompiled under SQL*Plus.
Provided that the TIP body change is independent, the new body compilation completes without errors and the former TIP specification remains valid. To determine if a specification has remained valid, issue the following from SQL*Plus:
SQL> column ddl_date format A22 heading 'LAST_DDL' SQL> select object_name, 2 object_type, 3 to_char(last_ddl_time,'MON-DD-YY HH:MM:SS') ddl_date, 4 status 5 from all_objects where owner = 'PGAADMIN' 6 order by object_type, object_name; OBJECT_NAME OBJECT_TYPE LAST_DDL STATUS ----------- ----------- -------------------- --------- PGADB2I PACKAGE NOV-24-1999 09:09:13 VALID PGADB2I PACKAGE BODY NOV-24-1999 09:11:44 VALID DB2IDRIV PROCEDURE DEC-30-1999 12:12:14 VALID DB2IDRVM PROCEDURE DEC-30-1999 12:12:53 VALID DB2IFORM PROCEDURE DEC-14-1999 11:12:24 VALID
The LAST_DDL column is the date and time at which the last DDL change against the object was done. It shows that the order of compilation was:
PGADB2I PACKAGE (the specification) DB2IDRVM PROCEDURE (1st client application depending on PGADB2I) DB2IFORM PROCEDURE (2nd client application depending on PGADB2I) DB2IDRIV PROCEDURE (3rd client application depending on PGADB2I) PGADB2I PACKAGE BODY (a recompilation of the body)
Note that the recompilation of the body does not invalidate its dependent object, the specification, or the client application indirectly.
You can also change the data structures or call exchange sequences of the remote host transaction. However, this kind of change is exposed to dependent client applications because the public datatypes or functions in the TIP specification will also change and necessitate recompilation, which in turn causes the Oracle server to recompile such dependent client applications.
SQL> column ddl_date format A22 heading 'LAST_DDL' SQL> select object_name, 2 object_type, 3 to_char(LAST_DDL_TIME,'MON-DD-YY HH:MM:SS') ddl_date, 4 status 5 from all_objects where owner = 'PGAADMIN' 6 order by object_type, object_name; OBJECT_NAME OBJECT_TYPE LAST_DDL STATUS ---------- ----------- --------------------- --------- PGADB2I PACKAGE NOV-24-1999 09:09:13 VALID PGADB2I PACKAGE BODY NOV-24-1999 09:11:44 INVALID DB2IDRIV PROCEDURE DEC-30-1999 12:12:14 INVALID DB2IDRVM PROCEDURE DEC-30-1999 12:12:53 INVALID DB2IFORM PROCEDURE DEC-14-1999 11:12:24 INVALID
Note that the recompilation of the specification has invalidated its dependent objects, the three client applications in addition to the package body. To complete these changes, the body must be recompiled to bring it into compliance with the specification and then the three client applications could be compiled manually, or the Oracle server compiles them automatically as they are referenced.
If the client applications are recompiled by the Oracle server as they are referenced, there is a one-time delay during recompilation.
Recompilation errors in the client application, if any, are due to:
If you make a mistake when you generate a tip (for example, if you alter a PG DD transaction definition, or if you've inadvertently specified the wrong version during regeneration), then the recompiled body will not match the stored specification; as a result, the Oracle integrating server would invalidate the specification and any dependent client applications.
You may have to regenerate and recompile the TIP and its dependent client applications to restore correct operation.
Refer to "Listing Dependency Management Information," in the Oracle9i Server Application Developer's Guide for more information.
To initialize and terminate a connection to the remote transaction program (RTP) and to process the buffers exchanged through the PGAXFER RPC, you are required to know:
Proper use of the UTL_RAW and UTL_PG functions is also required, to perform conversion of the data exchanged with the remote transaction. Refer to Appendix D, "The UTL_PG and UTL_RAW Interfaces" for detailed information about using these functions. Typically, this information is available to the remote transaction program developer and to the gateway administrator.
You are expected to know:
The resulting TIP should provide the function calls you need. Once a TIP is developed and stored in the Oracle integrating server database, it can be called by other client applications which need to access and control the remote transaction program for which the TIP was written.
You are expected to know how to control the remote transaction program and step it through all proper sequences. For example, using EMPT for employee update might first require an input to select one of several possible employee tables to update. Then each such choice results in further inputs and outputs specific to the type of table being updated. You are expected to know how to navigate among these choices.
The TIP is a transaction access method or transaction call runtime library which assists the application in controlling EMPT, without requiring you to know all of the specifics of gateway RPCs and data conversion.
A remote transaction program and its related TIP with client application must correspond on two key requirements:
The requirement to synchronize parameter datatype conversion means that the TIP function logic must perform all data conversion and buffering into the format expected by the receiving remote transaction program. The TIP function logic must also perform all data unbuffering from the format supplied by the sending remote transaction program and then convert the data to PL/SQL datatypes returned to the TIP caller, the client application, as PL/SQL parameters.
Assume the remote transaction program receives and then transmits a 75-byte record containing three fields:
Each field corresponds to a passed PL/SQL parameter. The TIP function must send logic, before calling the PGAXFER remote procedural call (RPC), to:
Each of the above three conversions requires different UTL_RAW and UTL_PG functions depending on whether the PL/SQL parameter is NUMBER, CHAR, VARCHAR2, or DATE.
After the PGAXFER RPC call, the record received from the remote transaction program must be converted in the reverse steps for each field:
These conversions differ based on the returned datatypes (NUMBER, CHAR, VARCHAR2, or DATE).
The requirement to synchronize APPC SENDs and RECEIVEs means that when the remote transaction program expects data parameters to be input, it issues APPC RECEIVEs to read the data parameters. Accordingly, the TIP must cause the gateway to issue APPC SENDs to write the data parameters to the remote transaction program. The reverse is also true; the TIP must cause the gateway to issue APPC RECEIVEs when the remote transaction program issues APPC SENDs.
The number of data parameters exchanged between the TIP and the gateway on each call can vary at the user's discretion, as long as the remote transaction program's SEND/RECEIVE requests are satisfied. For example, the remote transaction program data exchange sequence might be:
APPC SEND 5 fields (field1-field5) APPC RECEIVE 1 fields (field6) APPC SEND 1 field (field7) APPC RECEIVE 3 fields (field8 - field10)
The resulting TIP/application call sequence could be:
tip_call1(parm1 OUT,<-- APPC SEND field1 from remote TP parm2 OUT,<-- APPC SEND field2 from remote TP parm3 OUT);<-- APPC SEND field3 from remote TP tip_call2(parm4 OUT, <-- APPC SEND field4 from remote TP parm5 OUT); <-- APPC SEND field5 from remote TP
|
Note: At this point, the total data length expected by PL/SQL parameters 1-5 must equal the total data length sent in remote transaction program fields 1-5. Because an Oracle NUMBER datatype and a COBOL datatype can be different lengths for the same numeric value (their internal representations differ), a simple sum of lengths does not suffice. The internal representation of the remote data format must be known and embodied in the TIP conversion logic, as discussed in Step 4 of "TIP Body". |
tip_call3(parm6 IN OUT); --> APPC RECEIVE field6 in remote TP <-- APPC SEND field7 from remote TP tip_call4(parm8 IN, --> APPC RECEIVE field8 into remote TP parm9 IN, --> APPC RECEIVE field9 into remote TP parm10 IN); --> APPC RECEIVE field10 into remote TP
Notice that the remote transaction program's first five written fields are read by two separate TIP function calls (tip_call1 and tip_call2). This could also have been equivalently accomplished with five TIP function calls of one OUT parameter each, or a single TIP function call with five OUT parameters. Then the remote transaction program's first read field (field6) and subsequent written field (field7) corresponds to a single TIP function call (tip_call3) with a single IN OUT parameter (parm6).
This use of a single IN OUT parameter implies that the remote transaction program's datatype for field6 and field7 are both the same and correspond to the conversion performed for the datatype of parm6. If field6 and field7 were of different datatypes, then they would have to correspond to different PL/SQL parameters (for example, parm6 IN and parm7 OUT). However, they could still be exchanged as two parameters on a single TIP call or one parameter each on two TIP calls.
Lastly, the remote transaction program's remaining three RECEIVE fields are supplied by tip_call4 parms 8-10. They also could have been done with three TIP calls passing one parameter each or two TIP calls passing one parameter on one call and two parameters on the other, in either order. This flexibility permits the user to define the correspondence between the remote transaction program's operation and the TIP function calls in whatever manner best suits the user.
Thus, a remote transaction program expecting to send one field, then receive one field must correspond to separate TIP calls which do:
tip_callO(parmO OUT); <-- APPC SEND outfield from remote transaction program
PGAXFER RPC checks first for parameters to send but finds none and proceeds to receive parameters.
tip_callI(parmI IN); --> APPC RECEIVE infield to remote transaction program
PGAXFER RPC processes parameters to send and then checks for parameters to receive, but finds none and completes.
A single TIP call with an OUT parameter followed by an IN parameter does not work because the IN parameter is processed first regardless of its position in the parameter list.
The only exception is a parameter greater than 32K in length. In this case, the TIP builds additional send/receive "pseudo-parameters" internally to instruct the gateway to exchange additional buffers until the total length is satisfied. The remote host transaction must be programmed to expect and exchange multiple buffers for data fields exceeding 32K.
For example, if the remote transaction program sends 100 bytes, then the user's application and TIP calls must cause the PGAXFER RPC to receive 100 bytes. After the application and TIP have received 100 bytes from the PGAXFER RPC, then the next PGAXFER RPC call can send data to the remote transaction program, provided that the remote transaction program is ready to receive. The byte counts transferred to the remote transaction program must match exactly at both ends before reversing direction again.
Use the following guidelines to develop the package specification.
Declare a transaction instance number as an OUT parameter.
Refer to "PGAINIT and PGAINIT_SEC" in Appendix C, "Gateway RPC Interface".
Declare a transaction instance number as an IN parameter.
Refer to "PGATERM" in Appendix C, "Gateway RPC Interface".
Declare a transaction instance number as an IN parameter.
Declare user IN, IN OUT, or OUT parameters for data transfer.
Refer to "PGAXFER" in Appendix C, "Gateway RPC Interface".
Use the following guidelines to develop the package body.
TYPE tran_cid_tbl IS TABLE OF /* Table (array) of */ RAW(12) NOT NULL /* 12-byte RAW's */ INDEX BY BINARY_INTEGER; /* indexed by reentlvl */ trannum BINARY_INTEGER; /* trancid Table index parm */ cidraw0s RAW(12) := HEXTORAW('000000000000000000000000'); trancid tran_cid_tbl; /* APPC Conv ID returned */
Specify the Oracle database link assigned to the gateway node which communicates with the remote transaction program.
The call is of the form:
PGAINIT@dblink(convid, tpname, luname, modename, profname, synchlevel);
Refer to "PGAINIT and PGAINIT_SEC" remote procedural calls in Appendix C, "Gateway RPC Interface" for more information.
For each IN or IN OUT parameter passed by the calling application:
Local Application data format expected:
Remote Transaction Program data format expected:
Because of this requirement for composing data in its exact native format, you should seek advice or assistance from the remote transaction program developer. Remote transaction program listings of the data structures being exchanged are useful.
Reference atomic variables as passed, or PL/SQL record fields as "record_name.fieldname", or if other aggregate, use SUBSTR to extract needed fields. Then when converting to RAW (into send buffer) from a PL/SQL datatype of:
CAST_TO_RAW - recast user CHAR data into raw
CONVERT - convert raw data to remote NLS codepage
OVERLAY - place the result in the send buffer
CAST_TO_RAW - recast user VARCHAR2 data into raw
CONVERT - convert raw data to remote NLS codepage
OVERLAY - place the result in the send buffer
NUMBER_TO_RAW - change user NUMBER data to COBOL data
OVERLAY - place the result in the send buffer
Store the final RAW byte length of the converted parameter into its respective position in the send lengths list (this is the exact byte length as expected by the remote transaction program) and increment the send count.
For each IN OUT or OUT parameter passed by the calling application, put its length in the receive lengths list and increment the receive count.
Call the PGAXFER RPC passing the APPC conversation ID indexed by the transaction instance number of the targeted remote transaction program, and the send/receive parameters as previously initialized and built. Specify the Oracle database link assigned to the gateway node which communicates with the remote transaction program. The call is of the form:
PGAXFER@dblink (convid, sndbuf, sndbufl, sndlns, rcvbuf, rcvbufl, rcvlns) ;
Refer to Appendix C, "Gateway RPC Interface" for descriptions of the PGAXFER RPC.
Previous processing should have built a receive lengths list that corresponds to IN OUT or OUT parameters passed from the calling application. The actual receive count and actual lengths of received parameters have been placed in the received lengths list by the PGAXFER RPC upon return.
For the count of received parameters, extract each received parameter from the receive buffer using the actual length from the received lengths list, computing its starting offset from the previous offset plus the previous length. Then convert the extracted native parameter into an Oracle PL/SQL variable as follows.
Received parameters can be either atomic or aggregate datatypes. Atomic implies one parameter per Oracle variable. Aggregates, such as records or structures, must have each of their component fields extracted and separately converted to a PL/SQL datatype, one field per Oracle variable.
Remote Transaction Program data format received:
Use SUBSTR to extract the current receive parameter from the receive buffer, using the length from the receive lengths list, and computing the starting offset from the previous received parameter length plus 1. Then when converting from RAW, from the receive buffer, to a PL/SQL datatype of:
SUBSTR - extract raw data field from buffer
CONVERT - convert raw data from remote NLS codepage
CAST_TO_VARCHAR2 - recast raw data as varchar2
RPAD - right pad remainder of CHAR with blanks
SUBSTR - extract raw data field from buffer
CONVERT - convert raw data from remote NLS codepage
CAST_TO_VARCHAR2 - recast raw data as varchar2
SUBSTR - extract raw COBOL field from buffer
RAW_TO_NUMBER - change raw COBOL data to NUMBER
Then assign the result to an atomic variable as passed or to PL/SQL record fields as "record_name.fieldname", or if other aggregate, use OVERLAY to insert the result field.
Specify the Oracle database link assigned to the gateway node which communicates with the remote transaction program.
The call is of the form:
PGATERM@dblink (convid, '0') ;
Refer to Appendix C, "Gateway RPC Interface" for descriptions of the PGATERM RPC.
Use the following guidelines to initialize the package.
Refer to Appendix D, "The UTL_PG and UTL_RAW Interfaces" for descriptions of the following UTL_PG functions; Refer to pgadb2i.sql for examples of their use.
These function calls are always included in PGAU-generated TIPs. They issue the PGAINIT and PGATERM RPCs, respectively, to the gateway.
The client application calls the TIP initialization function as if it were any local PL/SQL function. For example:
mytran_number := 0; /* first transaction started*/ rc = tip_init(mytran_number); /* and init transaction */
Note that the application does not pass any remote transaction program name or network connection information. The TIP has such information internally coded as constants. All the application needs is to call the proper TIP for the requested remote transaction program.
This call serves the following two purposes:
This includes:
This transaction instance number must be passed to subsequent TIP transfer and terminate functions to identify to the gateway on which APPC conversation, and hence which iteration of a remote transaction program, the data is to be transmitted or communication terminated.
A single application can control multiple instances of the same remote transaction program (RTP) or multiple different RTPs, all concurrently. The APPC conversation ID is the TIP and gateway mechanism for routing the applications call to the intended remote transaction program.
However, to simplify the application's management of the transaction and to permit a single instance of a TIP to manage multiple conversations, the APPC conversation ID should be stored in an array of RAWs and the index to this particular element should be returned to the application as the transaction instance number.
The TIP must remember all active APPC conversation IDs and pass the correct one as the remote transaction program/conversation identifying parameter on every call. The TIP does this by using the transaction instance number passed from the application to index into the RAW array of APPC conversation IDs and passes the indexed APPC conversation ID to the gateway.
It is the application's responsibility to remember the transaction instance number of each active transaction and pass the correct one to each TIP function called for that transaction.
The client application calls the TIP termination function as if it were any local PL/SQL function. For example:
rc = tip_term(mytran_number); /* and terminate it */ mytran_number := 0; /* reset transaction instance to 0*/
After a transaction instance number has been passed on a TIP terminate call to terminate the transaction, or after the remote transaction program has abended, that particular transaction instance number might be forgotten and its corresponding entry in the RAW array of APPC conversation IDs reset.
|
 Copyright © 2001 Oracle Corporation. All Rights Reserved. |
|