Home

Oracle Database Gateway for APPC User's Guide, 11g Release 2

Contents

1. To determine which transaction version number was assigned this SOL query can be issued SELECT MAX pt version FROM pga_trans pt WHERE pt tname DB21 To determine additional information related to the updated version of DB21 this query can be used SELECT FROM pga_trans pt WHERE pt tname DB21 This example generates a new package using the previously defined new versions of the TRANSACTION CALL and DATA definitions GENERATE DB2I VERSION ttttt PKGNAME NEWDB21 OUTFILE pgadb2i where ttttt is the version number of the DB2I TRANSACTION definition queried after the previous DEFINE TRANSACTION updated DB2I Note that the previous PL SQL package files pgadb2i pkh and pgadb2i pkb are overwritten To keep the new package separate change the output file specification For example GENERATE DB21I VERSION ttttt PKGNAME NEWDB21 OUTFILE newdb21 A user s high level application now uses this TIP by referencing the PL SQL datatypes passed and returned Table F 2 provides a description of the TIP user transaction datatypes in package name NEWDB21 Table F 2 TIP User Transaction Datatypes for Package Name NEWDB2I Datatype Description NEWDB21 EMPNO Is a PL SQL variable corresponding to COBOL EMPNO NEWDB21 NEWEMP Is a PL SQL RECORD corresponding to COBOL NEWEMP NEWDB21 DB2
2. transaction was compiled using COBOL with the TRUNC B specified When this option is used binary data items define N compiler option dasPIC 9 4 or PIC 9 4 can actually contain values with 5 digits and binary data items defined as PIC 9 9 or PIC S9 9 can actually contain values with 10 digits Without COMPOPTS TRUNC BIN PGAU generates NUMBER 4 0 or NUMBER 9 0 fields for these data items resulting in possible truncation of the values When COMPOPTS TRUNC BIN is specified PGAU generates NUMBER 5 0 or NUMBER 10 0 fields for these data items avoiding any truncation of the values Care must be taken when writing the client application to ensure that invalid values are not sent to the remote host transaction Fora PIC 9 4 the value must be within the range 0 to 32767 fora PIC S9 4 the value must be within the range 32767 to 32767 fora PIC 9 9 the value must be within the range 0 to 2 147 483 647 and for a P IC S9 9 the value must be within the range 2 147 483 647t0 2 147 483 647 COBOL always reserves the high order bit of binary fields for a sign so the value ranges for unsigned fields are limited to the absolute values of the value ranges for signed fields For further information refer to the appropriate IBM COBOL programming manuals Procedural Gateway Administration Utility 2 9 PGAU Commands
3. X 6 S9 4 USAGE x 15 S9 4 USAGE X 20 X 3 X 4 x 10 Xx 8 S9 4 USAGE X 1 X 10 S9999999V99 S9999999V99 S9999999V99 COMP COMP COMP USAGE COM USAGE COM USAGE COM EMPR EC is to be redefined The assumption is that version 1 of the data definition for This causes a redefinition of the first EMPREC sample data definition without changing the version number Thus existing call and transaction definitions which referenced version 1 of EMPREC automatically reflect the changed EMPREC This change becomes effective when a TIP is next generated for a transaction that references the call which referenced version 1 of EMPREC This implicitly affects both versions of the transaction because both refer to EMPREC in the second call to update the employee data F 6 Oracle Database Gateway for APPC User s Guide Sample PGAU UNDEFINE Statements Sample PGAU UNDEFINE Statements These samples illustrate the deletion of a specific version of a definition which has multiple versions followed by deletion of all versions of a specific named definition Deletion of DATA Definitions UNDEFINE DATA EMPREC VERSION ddddd UNDEFINE DATA EMPREC VERSION ALL UNDEFINE CALL DB2IMAIN VERSION ccccc UNDEFINE CALL DB2IMAIN VERS all UNDEFINE TRANSACTION DB2I vers ttttt UNDEFINE TRANSACTION DB21 vers all Note that the pr
4. COBOL FILLER fields are recognized by PGAU by the spelling of the element name FILLER PGAU does not generate any data conversion for such elements but does require their space be properly allocated to preserve offsets within the records exchanged with the remote host transaction If a RENAMES or REDEF INES definition covers a FILLER element PGAU generates data conversion statements for the same area when it is referenced as a component of the RENAMES or REDEFINES variable Such data conversion reflects only the format of the RENAMES or REDEFINES definition and not the bounds of the FILLER definition Format Conversion Table D4 describes format conversion Table D 4 Format Conversion Descriptions Item El JUSTIFIED JUSTIFIED RIGHT JUSTIFIED LEFT Description This causes remote host transaction data to be converted as a PL SQL CHAR datatype according to character datatype as discussed in PIC X Datatype Conversions on page D 2 for both IN and OUT parameters IN parameter data passed from the application is stripped of its rightmost blanks and left padded as required Then it is sent to the remote host OUT parameter data is aligned as it is received from the remote host and padded with blanks as required on the left Then it is passed to the application This causes warnings to be issued during TIP generation No alignment is performed
5. tipname EMPREC_Typ SKILL SKILL_Key a HOME_ADDRESS ZIP is tipname EMPREC_Typ HOME_ADDRESS ZIP FIRST_FIVE tipname EMPREC_Typ HOME_ADDRESS ZIP LAST_FOUR Truncated and Non Unique Names PGAU truncates field names and corresponding PL SQL variable names when the name exceeds 26 bytes for fields within an aggregate record or group This is due to the need to suffix each field or PL SOL variable name with _Typ for group names _Tb1 for element names with a repeating group or 30 bytes due to the PL SQL limitation of 30 bytes for any name The rightmost four characters are truncated This imposes the restriction that names be unique to 26 characters Duplicate Names COBOL allows repetitive definition of the same group or element names within a record and the context of the higher level groups serves to uniquely qualify names However because PGAU generated TIPs declare PL SQL record variables which reference nested PL SQL records for subordinate groups and fields such nested PL SQL record types can have duplicate names Given the following COBOL definition note that ZIP is uniquely qualified in COBOL but the corresponding PL SQL declaration would have a duplicate nested record type for ZIP 01 EMPREC 05 HIREDATE PIC X 8 05 BIRTHDATE PIC X 8 05 SKILL PIC X 12 OCCURS 4 05 EMPNO PIC 9 4 05 EMPNAME 10 FIRST NAME PIC X 10 10 LAST NAME PIC X 15 05 HOME ADDRESS 10 STREET
6. Parameters Description ALL Shows all valid SET parameters ARRAYSIZE Shows the number of rows fetched at a time from the database CHARWIDTH Shows the column display width for CHAR data DATEWIDTH Shows the column display width for DATE data ECHO Shows echoing of commands entered from command files to ON or OFF FETCHROWS Shows the number of rows returned by a query LONGWIDTH Shows the column display width for LONG data MAXDATA Shows the maximum data size NUMWIDTH Shows the column display width for NUMBER data SERVEROUTPUT Shows debugging output from stored procedures that use DBMS_OUTPUT PUT and PUT_LINE commands Procedural Gateway Administration Utility 2 27 PGAU Commands SPOOL Table 2 9 Cont SHOW Parameter Descriptions Parameters Description STOPONERROR Indicates whether execution of a command file should stop if an error occurs TERMOUT Shows whether the terminal output for SQL commands is enabled or disabled TIMING Shows whether display of parse execute and fetch times both CPU and elapsed for each executed SQL statement is enabled or disabled VAR Is the same as the PRINT command in addition it shows all variables and their datatypes Examples Note that when you issue a SET command there will be no output if it is successful If you want to check whether your statement was executed successfully issue a SHOW command like the following PGAU gt show arraysize Arrays
7. TRANSACTION Correspondence The remote host transaction is defined with the PGAU DEFINE TRANSACTION statement with additional references to prior definitions of CALLs that the transaction supports You specify the remote host transaction attributes such as a transaction ID or name a network address or location system type such as IBM370 a Oracle National Language of the remote host Client Application Development SNA Only 4 13 Calling the TIP from the Client Application Note The PL SQL package name is specified when the transaction is defined this is the name by which the TIP is referenced and which the public function calls to be included within the TIP Each public function must have been previously defined with a PGAU DEFINE CALL statement which has been stored in the PG DD If you do not specify a package name TIP name in the GENERATE statement the transaction name you specified will become the package name by default In that case the transaction name tname must be unique and must be in valid PL SQL syntax within the database containing the PL SQL packages For more information refer to DEFINE TRANSACTION in Chapter 2 Procedural Gateway Administration Utility and Sample PGAU DEFINE TRANSACTION Statement in Appendix F Administration Utility Samples In this example the following DEFINE TRANSACTION statements are used to define a remote C
8. at the end of the command Parameters Table 2 8 describes the SET parameters Table 2 8 SET Parameter Descriptions Parameter Description ARRAYSIZE n Sets the number of rows fetched at a time from the database The default is 20 CHARWIDTH n Sets the column display width for CHAR data If entered with no argument it returns the setting to 9 which is the default DATEWIDTH Sets the column display width for DATE data If entered with no argument it returns the setting to 9 which is the default ECHO ON OFF Sets echoing of commands entered from command files to ON or OFF The default is OFF FETCHROWS n Sets the number of rows returned by a query This is useful with ordered queries for finding a certain number of items ina category the top ten items for example It is also useful with unordered queries for finding the first n records that satisfy a certain criteria LONGWIDTH n Sets the column display width for LONG data If entered with no argument it returns the setting to 80 which is the default MAXDATA n Sets the maximum data size It indicates the maximum data that can be received in a single fetch during a SELECT command The default is 20480 bytes 20K NUMWIDTH n Sets the column display width for NUMBER data If entered with no argument it returns the setting to 10 which is the default 2 26 Oracle Database Gateway for APPC User s Guide PGAU Commands SHOW Table 2
9. For UNIX based systems issue the following command from the gateway Oracle home ORACLE_HOME bin directory pg4tcpmap 6 6 Oracle Database Gateway for APPC User s Guide pg4tcpmap Tool Commands The gateway release number copyright information along with the following text appears This tool takes the IMS Connect TCP IP information such as host name and port number and maps them to your TIPs You may use this tool to insert or delete IMS Connect TCP IP information If you want to insert a row Type I If you want to delete a row type D Enter lt d gt and the pg4tcpmap tool will ask you what Side Profile Name you want to delete If the row does not exist you will receive an ORA 1403 error message Note Do not use SQL Plus to update the PGA_TCP_IMSC table If you have problems or incorrect data in the table use SORACLE_HOME dg4appc admin pgaimsc sql on Microsoft Windows or SORACLE_HOME dg4appc admin pgaimsc sql on UNIX based systems to re create the table and its index Querying the PGA_TCP_IMSC Table Use the regular SQL Plus select statement to query the table Example for Microsoft Windows C gt sqlplus userid password databasename SQL gt column hostname format A22 SQL gt column portnumber format A6 SQL gt select sideprofilename hostname portnumber imsdestid commitmode from pga_tcp_imsc SIDEPROF HOSTNAME PORTNU IMSDESTI Cc IMSPGA MVS08 US ORACLE C
10. Generate tname Defining and Generating the TIP After you have created your control file use PGAU to create the PG DD entries and the TIP specification files Note The user ID under which you run PGAU must have a write access to output the specification files pgau pkh pgau pkb and pgau doc where pgau is the default name and read access to the data definition source files Aname ext where dname ext will be specified in PGAU DEFINE DATA statement s Invoke PGAU against your PG DD stored in the Oracle Database Gateway for APPC Administrator s user ID For Microsoft Windows C gt pgau PGAU gt connect pgaadmin pw database_specification_string 3 6 Oracle Database Gateway for APPC User s Guide Compiling the TIP For UNIX based systems pgau PGAU gt connect pgaadmin pwtdatabase specification string Issue the following commands PGAU gt set echo on PGAU gt spool tname def PGAU gt tname ctl PGAU gt spool off The TIP is now ready to be compiled By default the GENERATE statement writes your TIP specifications to the following output files in your current directory pgau pkh TIP Header pgau pkb TIP Body pgau doc TIP content documentation Note You can optionally add spool and echo to your script tname ct1 or make other enhancements such as using PG DD roles and the PGAU GROUP statement for shared PG DDs If your gatewa
11. This section discusses the TIP documentation file that is produced when the user issues a PGAU GENERATE command This TIP content file describes the function calls and PL SQL variables and datatypes available in the TIP PGAU GENERATE always produces a TIP content file named tipname doc The filename is the name of the transaction that was specified in the PGAU GENERATE command and the filetype is always doc This TIP content file contains the following sections GENERATION Status This section contains the status under which the TIP is generated TIP Transaction This section identifies the defined transaction attributes These result from the PGAU DEFINE TRANSACTION definition TIP Default Calls This section identifies the syntax of the calls made by the user s application to initialize and terminate the transaction PGAU generates these calls into every TIP regardless of how the TIP or transaction is defined TIP User Calls This section identifies the syntax of the calls which the user defines for the application to interact with the transaction TIP User Declarations This section identifies the TIP package public datatype declarations implied by the user s data definition specified in each call parameter TIP User Variables This section contains TIP variables that can be referred to by applications or referenced by applications 3 8 Oracle Database Gateway for APPC User s Guide
12. VARCHAR2s can have a length less then the maximum due to deletion of shift out and shift in meta characters and sent PIC G RAW datatypes will have the shift out and shift in characters inserted as required by the remote host character set specified This is different from the conversions performed for PIC X data which is always a known fixed length and hence CHAR datatypes are used in TIPs for PIC X data fields However even when the PIC X field contains DBCS or MBCS data a CHAR variable is still used and padded with blanks if needed Some remote host applications bracket a PIC Gfield with PIC X bytes used for shift out shift in meta character insertion Such a COBOL definition might look like 01 MY_RECORD 05 SO PIC X 05 MY_MBCS_DATA PIC G 50 05 SI PIC X This is not processed correctly by PGAU because all three fields are defined and consequently treated as separate data items when conversion is performed To be properly processed the definition input to PGAU should be 01 MY_RECORD 05 MY_MBCS_DATA PIC G 51 The PGAU REDEFINE DATA statement can redefine the 3 field definition to the 1 field definition by specifying USAGE SKIP on fields SO and SI and 05 MY_MBCS_DATA PIC G 51 to redefine MY_MBCS_DATA The three REDEFINE statements can be placed in the PGAU input control file and thus the remote host definition need not be altered Cli
13. DEFINE CALL cnamel PARMS dnamel IN dname2 OUT EFINE CALL cname3 PARMS dname3 IN dname2 OUT s reduces the calls between the application and the TIP from r calls to two calls passing an IN and OUT parameter on each Because TIPs always process IN parameters before OUT ameters the data transmission sequence is unchanged However this consolidation is not always possible If your communication protocol is SNA Refer to Section Flexible Call Sequence on page 4 12 for more information about PGAU DEFINE CALL commands If your communication protocol is TCP IP Refer to Section Flexible Call Sequence on page 7 6 for more information about PGAU DEFINE CALL commands 3 Writea DEFINE TRANSACTION statement that contains every call specifying the network address and Globalization Support information DEFINE TRANSACTION tname CALLS cnamel cname2 cnameN ENVIRONMENT 1BM370 SIDEPROF profname TPNAME tpid LUNAME luname LOGMODE mode SYNCLEVEL n NLS_LANGUAGE charset 4 You can add a GENERATE statement to create the TIP specification GENERATE tname Note Youcan also add a REPORT statement to list the PG DD entries for tname REPORT TRANSACTION tname with CALLS with DATA Als o annotate the script with Comments REM this is a Comment Writing a PGAU Script Fi le
14. Datatype Conversions D 7 Conversion USAGE ASIS USAGE SKIP Table D 4 Cont Format Conversion Descriptions Item Description SYNCHRONIZED This causes the numeric field to be aligned on boundaries as SYNCHRONIZED RIGHT dictated by the remote host environment compiler language and datatype Numeric conversion is performed on the aligned data fields according to numeric datatype as discussed in PIC X Datatype Conversions on page D 2 for both IN and OUT parameters SYNCHRONIZED LEFT This causes warnings to be issued during TIP generation and no realignment is performed This is treated as documentation Numeric conversion is performed on the aligned data fields according to numeric datatype as discussed in PIC X Datatype Conversions on page D 2 for both IN and OUT parameters When USAGE ASIS is specified on the PGAU DEFINE DATA statement no conversion is performed Consequently each such field is simply copied to a PL SQL RAW of the same byte length No conversion translation or reformatting is done When USAGE SKIP is specified on the PGAU DEFINE DATA statement no data exchange is performed The data is skipped as if it did not exist Consequently such fields are not selected from the PG DD not reflected in the TIP logic and presumed absent from the data streams exchanged with the remote host The purpose of SKIP is to have definitions in the PG DD but not active perh
15. REPORT TRANSACTION tname REPORT TRANSACTION tname VERSION version 1 version 2 WITH DATA WITH CALLS This command reports all transaction definitions specified by transaction name tname REPORT ALL TRANSACTIONS tname WITH DATA WITH CALLS This command reports all transaction definitions in the PG DD REPORT ALL TRANSACTIONS WITH DATA WITH CALLS Procedural Gateway Administration Utility 2 25 PGAU Commands SET When WITH CALLS option is specified all call definitions associated with each selected transaction are also reported the call definitions precede each corresponding selected transaction in the report output When WITH DATA is specified all the data definitions associated with each selected call are also reported the data definitions precede each corresponding selected call in the report output For transaction reports specification of WITH DATA implies specification of WITH CALL The following command reports any unreferenced CALL or DATA definitions It also reports any TRANSACTION or CALL definitions that reference missing CALL or DATA definitions respectively REPORT ISOLATED The following command reports all definitions in the PG DD REPORT ALL Data definitions are reported followed by their associated call definitions followed by the associated transaction definition This sequence is repeated for every defined call and transaction in the PG DD wae You must place
16. and returns a transaction instance number to the application Optionally calls to initialize the conversation can be used to Override default RHT OLTP identification network address attributes and conversation security user ID and password Specify what diagnostic traces the TIP is to produce Refer to Chapter 8 Troubleshooting for more information about diagnostic traces PGAU generated TIPs provide four different initialization functions that client applications can call These are overloaded functions which all have the same name but vary in the types of parameters passed Three initialization parameters are passed The transaction instance number for RHT conversation identification The tranuse parameter is required on all TIP initializations TIP diagnostic flags for TIP runtime diagnostic controls The tipdiag parameter is optional Refer to Chapter 8 Troubleshooting for a discussion of TIP diagnostics TIP default overrides for overriding OLTP and network attributes The override parameter is optional The following four functions are shown as they might appear in the TIP Content documentation file Examples of client application use are provided later TYPE override_Typ IS RECORD tranname VARCHAR2 255 Transaction Program E transync BINARY_INTEGER RESERVED e trannls VARCHAR2 50 RESERVED El oltpname VARCHAR2 255 Logical Unit ed oltpmode VARCHAR2 255 LOG Mode Entr
17. on page 7 6 for more information about PGAU DEFINE CALL commands PGAU call entries are only defined once so eliminate any duplicates This call list defines the TIP function calls not the order in which they are used Note that the order in which each call is made is a behavior of the transaction and dictates the order of calls made by the high level application to the TIP which then calls the RHT through the Database Gateway server While this calling sequence is critical to maintaining the synchronization between the application and the RHT the TIP is only an access method for the application and has no knowledge of higher level sequencing of calls PGAU DEFINE DATA Command For each call in the RHT call list identify the RHT data structures being sent or received in the call buffers Make a data list of every such structure This list dictates a series of PGAU DEFINE DATA statements The two important parameters that you will use for DEFINE DATA are dname the name of the data definition to be created and dname ext the file in which the data definition is stored PGAU data entries are only defined once so eliminate any duplicates Note Move COBOL record layouts copybooks to the gateway system PGAU can use copybooks as input when defining the data items Once you have identified the data items to be exchanged use a file transfer program to download the copyboo
18. 4 Client Application Development SNA Only This chapter discusses how you will call a TIP and control a remote host transaction It also provides you with the steps for preparing and executing a gateway transaction This chapter assumes aremote host transaction RHT has already been written a a TIP corresponding to the RHT has already been defined using the steps described in Chapter 3 Creating a TIP Note If your gateway uses the TCP IP support for IMS Connect refer to Chapter 7 Client Application Development TCP IP Only for information about calling a TIP and controlling a remote host transaction This chapter contains the following sections Overview of Client Application on page 4 1 Preparing the Client Application on page 4 3 Understanding the Remote Host Transaction Requirements on page 4 3 Customized TIPs for Each Remote Host Transaction on page 4 6 Client Application Requirements on page 4 6 a Ensuring TIP and Remote Transaction Program Correspondence on page 4 10 Calling the TIP from the Client Application on page 4 14 Exchanging Data on page 4 19 a Executing the Application on page 4 20 a APPC Conversation Sharing on page 4 20 Application Development with Multi Byte Character Set Support on page 4 25 Modifying a Terminal Oriented Transaction to Use APPC on page 4 26 a Privileges Needed to Use TIPs on page 4 27 Overview of Client Applic
19. 4 4 7 3 PGDD Data Dictionary environment sequence numbers A 1 pgddausr sql file 4 27 7 16 pgddcr8 sql file 2 5 A 5 PGDL Procedural Gateway Definition Language 2 2 B 1 definition 1 4 pgtflip 7 14 pgtflipd 1 19 pgtflipd sql 7 10 pgtflipd sql file 7 4 7 14 E 1 pgtflip pkb 1 6 1 7 pgtflip pkb file 1 18 7 2 7 4 pgtflip pkh 1 6 pgtflip pkh file 1 18 pgtflip sql file 7 4 PIC9 8 4 D 4 PICG 8 4 datatypes 4 25 7 15 PIC G datatype conversions D 3 PIC G datatypes D 2 PIC X D 2 PIC X datatypes 8 4 D 2 PKGEX DC diagnostic option 8 5 PKGEX DR GENERATE diagnostic option 8 2 PL SQL 1 5 call A 9 code B 1 code generator 1 2 8 4 data length limits 8 8 datatypes 1 8 4 7 4 8 4 9 4 11 F 2 F 5 converted to RAW 1 9 developing TIPs D 1 enabling a trace 8 12 function in the gateway 1 1 1 8 invoking DG4APPC 1 11 1 15 naming algorithms D 8 delimiters D 8 duplicate names D 9 qualified compound names D 8 parameters 4 14 7 8 record format F 4 stored procedure 1 11 transferring data using RAW datatype C 1 UTL_PG package function 1 5 UTL_RAW function 1 4 variable names D 9 datatype conversion D 8 variables 3 8 D 6 D 7 D 9 PL SQL package 2 3 2 7 2 29 2 31 3 1 4 4 8 2 B 1 E 2 components 4 3 7 3 contents package specification 4 3 7 3 DBMS_PIPE 3 1 definition 1 4 1 5 execute authority 4 20 7 14 function 4 2 7 2 functions 1 8 grants required 3 1 p
20. Administration Utility for more information about this parameter Recompile the TIP body under SQL Plus Avoid recompiling the TIP specification Controlling TIP Runtime Conversion Warnings After the TIP has been regenerated the issuance of runtime warnings is under control of the application By default warnings are suppressed and are only issued when they are enabled Errors and exceptions are always issued if they occur To enable the issuance of warnings an additional parameter must be supplied when calling the TIP initialization function This parameter isa CHAR 8 datatype and each character position controls a particular TIP runtime diagnostic function To enable warnings in yourt ip the client application should call the TIP initialization function with the statement rc yourtip_init trannum 10000000 8 6 Oracle Database Gateway for APPC User s Guide Suppressing TIP Warnings and Tracing The following is input to the TIP trace pipe inlet at initialization time UTL_PG warnings enabled Controlling TIP Runtime Function Entry Exit Tracing To enable function entry exit tracing in yourt ip the client application should call the TIP initialization function with the statement rc yourtip_init trannum 01000000 The following is input to the TIP trace pipe inlet at initialization time function entry exit trace enabled tipname_init entered time date time stamp Controlling
21. Error Messages manual wmsgtext is a VARCHAR2 OUT parameter value containing the fully formatted warning message in ORA xxxxx format where xxxxx is the decimal warning number documented in the Oracle Database Error Messages manual wmsgfill is a VARCHAR2 OUT parameter value containing the list of warning message parameters to be substituted into a warning message in the following format warnparm1 warnparm2 warnparmn where each warning parameter is delimited by a double semicolon Defaults None Return Value A BINARY_INTEGER value containing a status return code A return code of 0 indicates that wmsgno wmsgtext and wmsg i11 are assigned and valid C 10 Oracle Database Gateway for APPC User s Guide NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values Error and Warning Messages If you receive an ORA xxxx error or warning message refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it Table C 16 describes the error messages you could receive Table C 16 WMSG Function Errors Error Description 1 indicating the warning specified by wmsgitem was not found in wnsgb1k 2 indicating an invalid message block 3 indicating wmsgb1k is too small to contain the warning associated with wmsgitem A partial or no warning message might be present for this particular wmsgi tem 4 indicating there are too many substituted warning par
22. 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 Determine if a Specification Has Remained Valid To determine if a specification has remained valid issue the following statements from SOL Plus depending upon your communication protocol a If your gateway is using the SNA communication protocol issue the following SQL gt column ddl_date format A22 heading LAST_DDL SQL gt select object_name E 2 Oracle Database Gateway for APPC User s Guide PL SQL Package and TIP File Separation 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 PGADB21I PACKAGE NOV 24 1999 09 09 13 VALID PGADB21I 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 cl
23. L compiler name compopts COBOL compiler options no values are supported at this time C 12 Oracle Database Gateway for APPC User s Guide D Datatype Conversions You must convert datatypes and data formats properly when you are using the PGAU tool to generate TIPs and when you are developing a custom TIP using PL SQL and the UTL_RAW and UTL_PG functions Read this appendix to learn about datatype conversion as it relates to TIPs This appendix contains the following sections Length Checking on page D 1 Conversion on page D 2 Length Checking PGAU generated TIPs perform length checking at the end of every parameter sent and received Table D 1 provides a list of length parameters generated by PGAU Table D 1 Length Parameters Parameter Description expected length Is computed by PGAU when the TIP is generated convert length Is summed by the TIP from each converted field send length Is the transmitted send data length and is also equal to the actual length for send parameters receive length Is the transmitted receive data length An exception is raised when the convert length of a sent parameter does not equal its expected length This occurs if too many or too few send field conversions are performed An exception is raised when the convert length of a received parameter does not equal its received length These length exceptions result when too few or too many conversions are performed A
24. PGAINIT and PGAINTT_SEC setinu anreisen io i a a a aiies reitt B 1 PGAXFER ios sli ianea IA li ada B 4 PETER Mais de B 5 PEATONES B 6 PEATRA Cosina da il dana B 6 The UTL_PG Interface UTE PG BaT AE 1 K AEEA A di ER AE E C 1 Common Parametersiotciiaita lito idiota arts ath C 2 Common Input Parameters cccccccceseessseseeeeseesceesesesseseecsensecessesesesesesessseeseesesesseseessenaeeeess C 2 Common Output Parameter isinisi aeee aara aaa a a aaae a aaaea aatas C 2 RAW TO NUMP Ro e ida C 3 NUMBER TORA Wiisiinsasi cl a rin diaria Es C 4 MAKE_RAW_TO_NUMBER_FORMAT cccccccccsssssesscesceesecssessecsecsseesecesseseseceeseseceseeeeeeseeeneenes C 5 MAKE_NUMBER_TO_RAW_FORMAT eocccccnconccnncononnnonnonononncnnnonncnnnon cnn nncn nc nano nn o nro nana nonrna nan ncinss C 6 RAW TO NUMBER FORMAT un A A ees C 8 NUMBER_TO_RAW_FORMAT cccsssssssssesssescessesscescecsecssecsecssecseceseeascesseseseeeseseneeseesaecaeeesecaes C 8 WMSGEN T na ele hel hd EA a it A er een ice C 9 WM obras llibre id basta C 10 NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values oociconnnninnicnnnnnicincninnnnoninoss C 11 Datatype Conversions Length Checking unica a a tb dnde ate D 1 Parameters Over 32K in Len glhiicioo circa Aia bbc iia D 2 CONV ELSION Li A A a Aid D 2 USAGE PASS ris e a tee AA ie een A ADA D 2 USAGE ASIS J en oa A e D 8 USAGE SKI P a A AL Sia D 8 PL SOL Naming Algorithms sse dani D 8 Tip Internals Background Reading issin in
25. Preparing the Client Application oonionncnnnnnnoninininnnnannncncncononocnnocnconononnrononono nono rn roo no raro rara n AE 4 3 Understanding the Remote Host Transaction Requirement ooocccninnnnncicnnoninoninonanonanononananononononos 4 3 TIP Content anid Purposes insurgir neaei eea a aaa caos AA Ea aE tothe dira Maen bc e 4 3 Remote Host Transaction Types senepiu ii rd 4 4 One Shot Transactions aeree aiae ened E a E SE eee 4 4 Persistent Transactions 2 22 cec ns estes bene ile coed e i e a a alla a E a aS 4 5 Multi Conversational Transactions ccccsccsccessesscessesssssceescesceseecsecescssecaeceseeseceeeeseseeeseeseeeees 4 5 Customized TIPs for Each Remote Host Transaction ccccccccecessesceseeseeseeeeeececeacesecaeeaeeeeeaeeaees 4 6 Client Application Requirement ooconnicinnnnococoninononacanononcncnconanocnrnrononononn nono ona nono rn ron ana racer canoa rannnns 4 6 Ensuring TIP and Remote Transaction Program Correspondence oocccinionononiconaninananacaninanancnanos 4 10 DATA Correspondence ni mirisni innon eni cai aa A A 4 10 CALL C orrespondencesmiciotorivasensaccdniocin dad elven srvngets Panas oidor a EEE 4 11 Flexible Call Sequence mistica clio e diana lili dada bien dotada cedido 4 12 Call Correspondence Order RestrictiOWMS oconoconononononennrnenrncnnnnnarnrennanonnnannrneroraronannnraranos 4 13 TRANSACTION Correspondence sssi enpe A EA parE EEEa debian 4 13 Calling the TIP from the Clie
26. called the TIP or transaction interface package precompiled in the Oracle database Because there are no additional software layers on the remote host overhead occurs only when your program executes Location transparency Client applications need not be operating system specific For example your application can call a program in a CICS Transaction Server for z OS If you move the program to a CICS region on AIX then you need not change the application Application transparency Users calling applications that execute a remote transaction program are unaware that a request is sent to a host a Flexible interface You can use the gateway to interface with existing procedural logic or to integrate new procedural logic into an Oracle database environment a Oracle database integration The integration of the Oracle database with the gateway enables the gateway to benefit from existing and future Oracle database features For example the gateway can be called from an Oracle stored procedure or database trigger a Transactional support The gateway and the Oracle database allow remote transfer updates and Oracle database updates to be performed in a coordinated fashion a Wide selection of tools The gateway supports any tool or application that supports PL SQL a PL SQL code generator The Oracle Database Gateway for APPC provides a powerful development environment including a data dictionary to store information rele
27. pgtflip pkb 1 18 7 2 7 4 pgtflip pkh 1 18 7 4 tipname doc 3 8 4 10 4 14 7 8 tipname pkb 8 5 tname ctl 3 5 3 6 flexible call sequence on gateway using SNA 4 12 on gateway using TCP IP 7 6 FLIP and pgacics PL SQL stored procedure on gateway using SNA 1 11 transaction in CICS 1 11 transaction in IMS 1 15 format conversion D 5 function PGATERM B 5 PGAXFER 4 4 7 3 B 4 UTL_PG C 1 functions see RPC remote procedural call See UTL_PG see UTL_PG see UTL_RAW G gateway access to IBM datastores 1 2 communication 1 2 overview 1 8 with CICS in mainframe on gateway using SNA 1 11 components 1 7 creating a TIP 3 1 enabling a trace 8 12 features application transparency 1 2 code generator 1 2 fast interface 1 2 flexible interface 1 2 location transparency 1 2 Oracle database integration 1 2 performs automatic conversions 1 3 site autonomy and security 1 3 support for tools 1 2 initialization files 1 3 overview 1 1 using TCP IP 1 1 remote procedure definition 1 4 remote transaction initiation using SNA 1 9 using TCP IP 1 9 remote transaction termination using SNA 1 9 using TCP IP 1 9 tracing 8 10 transaction types on gateway using SNA 1 10 on gateway using TCP IP 1 14 gateway sample files using SNA pgadb2i pkb 1 6 pgadb2i pkh 1 6 using TCP IP pgadb2i pkb 1 6 pgadb2i pkh 1 6 gateway server 5 5 function in commit confirm architecture 5 5 transaction log ta
28. this step for each user ID requiring access to the packages 7 16 Oracle Database Gateway for APPC User s Guide Privileges Needed to Use TIPs No script has been provided to perform public grants To do this issue the following commands For Microsoft Windows C gt sqlplus tip_owner pw database_specification_string SQL gt grant execute on tipname to PUBLIC For UNIX based systems sqlplus tip_owner pw database_specification_string SQL gt grant execute on tipname to PUBLIC Client Application Development TCP IP Only 7 17 Privileges Needed to Use TIPs 7 18 Oracle Database Gateway for APPC User s Guide 8 Troubleshooting This chapter discusses diagnostic techniques and aids for determining and resolving problems with data conversion truncation and conversation startup It also describes how to collect the data when the debugging trace option is on You will want to trace the PL SQL stored procedures only when you suspect problems Do not run with tracing enabled during normal operations because it will affect performance This chapter contains the following sections TIP Definition Errors on page 8 1 Problem Analysis with PG DD Diagnostic References on page 8 2 Problem Analysis with PG DD Select Scripts on page 8 3 Data Conversion Errors on page 8 4 Problem Analysis with TIP Runtime Traces on page 8 5 a TIP Runtime Trace Controls on page 8 6 Suppress
29. 0 Content Data definition number Primary key pga_data data pga_call_ parm data Set from an Oracle sequence object fname varchar2 255 Extracted or derived name of a field if dname defines aggregate data Max length gt COBOL name length plsfvar varchar2 30 PL SQL variable name of subfield in aggregate data for reference in PL SQL Max length gt PL SQL variable length updtdate date Audit trail date time this control record last updated updtuser varchar2 30 Audit trail user id program which last updated this record fld number 9 0 Clause or field within data definition id no Foreign key pga_data_values fld Set from an Oracle sequence object pos number 9 0 Relative position number of each field defined within an aggregate data item for example 1 2 3 and so on or NULL if data is atomic usage varchar2 6 Usage of this data field PASS SKIP NULL ASIS Max length gt 4 char string length A 12 Oracle Database Gateway for APPC User s Guide PG DD Active Dictionary Table A 20 Cont pga_fields Column Type Content mask varchar2 30 Datatype or Mask value For example S9 4 X 24 VARCHAR2 24 BINARY_INTEGER 16 NULL When NULL item defined is assumed to be a COBOL group or PL SQL nested record Max length gt arbitrarily chosen maskopts varchar2 100 Datatype or Mas
30. 03 05 03 52 INVALID PGTFLIP PROCEDURE APR 24 03 05 04 29 INVALID Recompile the TIP Body 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 database compiles them automatically as they are referenced If the client applications are recompiled by the Oracle database as they are referenced there is a one time delay during recompilation Recompilation errors in the client application if any are due to customer changes in the client application source a an altered PG DD definition for the TIP if the TIP has been regenerated the wrong version being generated from multiple transaction entry versions saved in the PG DD if the TIP has been regenerated Inadvertent Alteration of TIP Specification If you make a mistake when you generate a tip for example if you alter a PG DD transaction definition or if you have inadvertently specified the wrong version during regeneration then the recompiled body will not match the stored specification as a result the Oracle database would invalidate the specification and any dependent client applications E 4 Oracle Database Gateway for APPC User s Guide PL SQL Package and TIP File Separation You may have t
31. 3 A 2 Oracle Database Gateway for APPC User s Guide PG DD Environment Dictionary Table A 3 pga_environments Column Type Content name varchar2 16 not null Environment Primary key env number 9 0 notnull Env id Foreign key pga_env_attr The pga_env_attr table stores the types of environmental attributes as presented in Table A 4 Table A 4 pga_env_attr Column Type Content name varchar2 16 notnull Attribute Primary key attr number 9 0 notnull Attribute id Foreign key coltype varchar2 4 not null Attr value type Foreign key pga_env_values The pga_env_values table stores the values for environments as presented in Table A 5 Table A 5 pga_env_values Column Type Content envi number 9 0 notnull Env id Primary key attr number 9 0 notnull Attribute id Primary key numval number 9 0 Numeric attribute value charval varchar2 64 Character attribute value dateval date Date attribute value pga_compilers The pga_compilers table stores the compiler environment names as presented in Table A 6 Table A 6 pga_compilers Column Type Content name varchar2 16 not null Compiler name Primary key plscomp varchar2 30 PLS compiler name Secondary key Database Gateway for APPC Data Dictionary A 3 PG DD Environment Dictionary Table A 6 Cont pga_compilers Column Type Content envit number
32. 4 USAGE COMP 49 LASTNAME TEXT PIC X 15 10 WORKDEPT PIC X 3 Administration Utility Samples F 1 Sample PGAU DEFINE CALL Statements L0 PHONENO PIC X 4 0 HIREDATE PIC X 10 0 JOB PIC X 8 10 EDLEVEL PIC S9 4 USAGE COMP 10 SEX PIC X 1 0 BIRTHDATE PIC X 10 0 SALARY PIC S9999999V99 USAGE COMP 3 0 BONUS PIC S9999999V99 USAGE COMP 3 0 COMM PIC S9999999V99 USAGE COMP 3 DEFINE DATA DB2INFO PLSDNAME DB2 USAGE PASS LANGUAGE IBMVSCOBOLII INFILE db2 cob where the file db2 cob contains the following 01 DB2 05 SQLCODE PIC S9 9 COMP 4 05 SQLERRM 49 SQLERRML PIC S9 4 COMP 4 49 SQLERRT PIC X 70 05 DSNERRM 49 DSNERRML PIC S9 4 COMP 4 49 DSNERRMT PIC X 240 OCCURS 8 TIMES INDEXED BY ERROR INDEX Sample PGAU DEFINE CALL Statements DEFINE CALL DB2IMAIN PKGCALL PGADB2I_MAIN PARMS EMPNO IN EMPREC OUT DEFINE CALL DB2IDIAG PKGCALL PGADB2I_DIAG PARMS DB2INFO OUT Sample PGAU DEFINE TRANSACTION Statement DEFINE TRANSACTION DB2I CALL DB2IMAIN DB2IDIAG SIDEPROFILE CICSPROD TPNAME DB21 LOGMODE ORAPLU62 SYNCLEVEL 0 NLS_LANGUAGE AMERICAN_AMERICA WE8EBCDIC37C Sample PGAU GENERATE Statement GENERATE DB2I PKGNAME PGADB21 OUTFILE pgadb2i A user s high level application now uses this TIP by referencing these PL SQL datatypes passed and returned F 2 Oracle Database Gateway for APPC User s Guide Sampl
33. COMPOPTS TRUNC BIN is specified PGAU generates NUMBER 5 0 orNUMBER 10 0 fields for these data items avoiding any truncation of the values Care must be taken when writing the client application to ensure that invalid values are not sent to the remote host transaction For a PIC 9 4 the value must be within the range 0 to 32767 fora PIC S9 4 the value must be within the range 32767 to 32767 fora PIC 9 9 the value must be within the range 0 to2 147 483 647 and fora PIC S9 9 the value must be within the range 2 147 483 647 to 2 147 483 647 COBOL always reserves the high order bit of binary fields for a sign so the value ranges for unsigned fields are limited to the absolute values of the value ranges for signed fields For further information refer to the appropriate IBM COBOL programming manuals Refer to USAGE PASS in Appendix D Datatype Conversions for information about how PGAU converts COBOL statements woe a You must place at the end of the command Purpose Comments can either be introduced by the REM command or started with the two character sequence and terminated with the two character sequence Use the REM command to start a Comment line Syntax The REM command has the syntax REM Comment Parameters Comment is any strings Examples REM This is a Comment REM Usage Notes You do not need to place at
34. Is a PL SQL RECORD corresponding to COBOL DB2 and the application calls NEWDB21 PGADB21_INIT trannum NEWDB21 PGADB21_MAIN trannum empno newemp Administration Utility Samples F 5 Sample PGAU REDEFINE DATA S tatements NEWDB21 PGADB21_DIAG trannum NEWDB21 PGADB21_TERM trannum db2 i termtype Sample PGAU REDEFINE DATA Statements Single field redefinition in which El REDEFINE DATA EMPREC P L F P LSDNAME DCLEMP ANGUAGE IBMVSCOBOLIT IELD EDLEVEL LSFNAME PLSRECTYPE 10 EDLEVEL PIC S9 4 i By default this redefines the latest version of DLEVEL USAG USAGE IS COMP 3 EMPR latest call and transaction definitions which refer to it E becomes COMP 3 EC which implicitly affects the Sample multi field redefinition in which the employee s first and last name fields are expanded and the employee s middle initial is removed REDEFINE DATA EMPREC VERSION 1 PLSDNAME DCLEMP LANGUAGE IBMVSCOBOLIT INFILE emp1 cob where the file emp1 cob contains the following 01 DCLEMP 10 EMPNO 49 49 49 JOB SEX BONUS COMM eS SS EO DU e A 10 FIRSTNME FIRSTNME LEN FIRSTNME TEXT 10 LASTNAME 49 LASTNAME LEN LASTNAME TEXT WORKDEPT PHONENO HIREDATE EDLEVEL BIRTHDATE SALARY PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC PIC
35. Mainframe Using SNA illustrates the communications process described in steps 1 through 4 Introduction to Oracle Database Gateway for APPC 1 11 Overview of a Gateway Using SNA Figure 1 3 Communication Between the Oracle Database and the Mainframe Using SNA Pue ta Operating System pu Oracle Database lt SQL gt execute pgacics snoitalutargnoC Congratulations PL SQL procedure successfully completed y Client Oracle Database Gateway PGAINITO PGA PGAXFER PGA PGATERMOPGA je APPC 2 3 7 Mainframe Aui a aea ee 2 22 Me ioe doe ee a ji i CICS FLIP Writing TIPs to Generate PL SQL Programs Using SNA Most transactions using SNA communication protocol are much larger and more complex than the sample pgacics sql file referred to in Figure 1 3 Communication Between the Oracle Database and the Mainframe Using SNA Additionally communication with a normal sized RTP would require you to create an extremely long PL SQL file PGAU function generates the PL SQL procedure for you The following is a brief description of the four steps necessary for you to generate a TIP Refer to Chapter 3 Creating a TIP for detailed information about this procedure and refer to Chapter 2 Procedural Gateway Administration Utility for more info
36. PIC X 20 10 CITY PIC X 15 10 STATE PIC XX 10 ZIP 15 FIRST FIVE PIC X 5 15 LAST FOUR PIC X 4 05 DEPT PIC X 45 Datatype Conversions D 9 Conversion 05 OFFICE ADDRESS 10 STREET 10 CITY 10 STATE 10 ZIP 15 FIRST FIVE 15 LAST FOUR 05 JOBTITLE PIC X 20 PIC X 15 PIC XX PIC X 5 PIC X 4 PIC X 20 PGAU avoids declaring duplicate nested record types and generates the following PL SQL SKILL_Key BINARY_INTEGER TYPE SKI LL_Tbl is TABLE of CHAR 12 INDEX by BINARY_INTEGER TYPE EMPNAME_Typ is RECORD FIRST_NAME CHAR 10 LAST_NAME CHAR 15 TYPE ZIP_Typ is RECORD FIRST_FIVE CHAR 5 LAST_FOUR CHAR 4 TYPE HOME_ADDRESS_Typ is RECORD STREET CHAR 20 CITY CHAR 15 STATE CHAR 2 ZIP ZIP_Typ TYPE OFFICE_ADDRESS_Typ is RECORD STREET CHAR 20 CITY CHAR 15 STATE CHAR 2 ZIP ZIP_Typ TYPE EMPREC_Typ is RECORD HIREDATE CHAR 8 BIRTHDATE CHAR 8 SKILL SKILL_Tbl EMPNO NUMBER 4 0 EMPNAME EMPNAME_Typ HOME_ADDRESS HOME_ADDRESS_Typ DEPT CHAR 45 OFFICE_ADDRESS OFFICE_ADDRESS_Typ JOBTITLE CHAR 20 However in the case where multiple nested groups have the same name but have different subfields see Z1 05 HOME ADDRESS P following 10 STREET PIC X 20 10 CITY PIC X 15 10 STATE PIC XX 10 ZIP 15 LEFTMOST FOUR PIC X 4 15 RIGHMOST FIVE PI
37. Refer to Sample PGAU DEFINE CALL Statements on page F 2 in Appendix F for examples of DEFINE CALL commands DEFINE CALL Usage Notes a Version of the CALL definition is not specified and defaults to NEXTVAL of the Oracle Sequence Object for CALL Procedural Gateway Administration Utility 2 7 PGAU Commands PKGCALL and PARMS can be specified in either order a You need to place a semi colon at the end of the command DEFINE DATA Purpose This command creates a new version of the data definition in the PG DD Syntax DEFINE DATA dname PLSDNAME plsdvar USAGE PASS ASIS SKIP COMPOPTS options LANGUAGE language definition INFILE filespec Parameters Table 2 2 describes the EFINE DATA parameters Table 2 2 DEFINE DATA Parameter Descriptions Parameter Description DATA dname PLSDNAME plsdvar USAGE PASS ASIS SKIP COMPOPTS options LANGUAGI El language is a mandatory parameter It is the name of the data definition to be created is an optional parameter It is the name of the PL SQL variable associated with dname It becomes the name of a PL SOL variable if the dname item is atomic data or a PL SQL record variable if the dname item is aggregate data such as a record or structure when the TIP is generated is an optional parameter It specifies the way the TIP handles the data items when
38. Refer to USAGE PASS in Appendix D Datatype Conversions for information about how PGAU converts COBOL statements You need to place a semi colon at the end of the command DEFINE TRANSACTION Purpose This command creates a new version of the transaction definition in the PG Data Dictionary Syntax DEFINE TRANSACTION tname CALL cname VERS callvers ENVIRONMENT name SIDEPROFILE name LUNAME name TPNAME name LOGMODE name LUNAME name TPNAME name LOGMODE name SYNCLEVEL 0 1 2 NLS_LANGUAGE n1sname REMOTE_MBCS nlsname LOCAL_MBCS nlsname Parameters Table 2 3 describes the 1 D EFINE TRANSACTION parameters Table 2 3 DEFINE TRANSACTION Parameter Descriptions Parameter Description TRANSACTION tname CALL cname VERS callvers ENVIRONMENT name A mandatory parameter It is the name of the transaction definition to be created If you do not specify a package name TIP name in the GENERATE statement the transaction name specified here will become the package name by default In that case the tname must be unique and must be in valid PL SQL syntax within the database containing the PL SQL packages A mandatory parameter It specifies a list of previously defined calls created with DEFINE CALL which taken together comprise this transaction The order in which the calls are s
39. TCP IP for IMS Connect 1 14 NUMBER_TO_RAW and RAW_TO_NUMBER argument values C 11 NUMBER_TO_RAW function C 4 errors C 5 NUMBER_TO_RAW_FORMAT function C 8 O OCCURS DEPENDING ON D 7 OCCURS n TIMES D 6 OLTP and TCP IP 1 5 1 7 commit confirm transaction log 5 3 definition 1 5 forget recovery transaction 5 3 functional requirements of the gateway 5 4 in commit confirm 5 2 in gateway architecture featuring SNA 1 7 in gateway using TCP IP 1 7 logic flow for successful commit 5 5 Index 4 only IMS supported on gateway using TCP IP 1 3 1 5 remote 1 1 security considerations 4 19 7 13 transaction logging code 5 3 one shot transaction types 1 10 4 4 4 7 5 4 online transaction processor See OLTP operating system role in gateway installation 1 7 Oracle database 1 9 component of the gateway 1 7 definition 1 5 function in gateway communication on gateway using TCP IP 1 14 multiple servers on the gateway using SNA 1 7 using TPC IP 1 7 precompiles PL SQL package 1 2 role in gateway communication 1 8 simple communication on gateway using SNA 1 10 on gateway using TCP IP 1 14 steps to communication between server and mainframe using SNA 1 11 stores PL SQL 1 4 Oracle Database Gateway for APPC also see gateway compatibility with version 3 4 0 4 22 development environment 1 2 See also gateway server Oracle global transaction ID 5 2 5 3 5 4 5 7 Oracle integrating server 4 2 and role in
40. The previous section describes the steps you need to follow in order to execute PGAU statements via your PGAU command line processor As a time saving measure you can choose to write all of the statements DEFINE DATA DEFINE CALL and DEFINE TRANSACT order TON into a single PGAU script file named tname ct1 in the following 1 define data Creating a TIP 3 5 Defining and Generating the TIP 2 define call 3 define transaction 4 generate Caution Because you will probably run this script more than once you should include UNDEFINE statements first to remove any previous entries in the PG DD This is an example of a tname ct1 PGAU script file DEFINE TRANSACTION tname Version all DEFINE CALL cnamel Version all DEFINE CALL cname2 Version all DEFINE DATA dnamel Version all FINE DATA dname2 Version all DEFINE DATA dname3 Version all FINE DATA dnamel LANGUAGE IBMVSCOBOLII INFILE dnamel ext E DATA dname2 LANGUAGE IBMVSCOBOLII INFILE dname2 ext FINE DATA dname3 LANGUAGE IBMVSCOBOLII INFILE dname3 ext E CALL cnamel PARMS dnamel IN dname2 OUT DEFINE CALL cname2 PARMS dname3 IN dname2 OUT DEFINE TRANSACTION tname CALLS cnamel cname2 cnameN ENVIRONMENT IBM370 SIDEPROF profname TPNAME tpid LUNAME luname LOGMODE mode SYNCLEVEL n NLS_LANGUAGE charset H Eyga t
41. about creating the PGA_TCP_IMSC table then depending on your platform refer to Chapter 13 of the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Chapter 10 of Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows E 1 In a PGAINIT procedure call the user must specify a Side Profile Name and TP Name The values of these parameters will be inserted into a table named PGA_TCP_IMSC PG4TCPMAP Commands TCP IP Only 6 1 Populating the PGA_TCP_IMSC Table Configure userid and password before running gateway mapping tool Before executing the pg4tcpmap tool you must configure a valid userid and password and TNSNAMI ES alias for the Oracle database where the PGA_TCP_IMSC table resides You must specify the userid password and database in the PGA_TCP_ US gateway initialization file SORACLE_ HOM ER PGA_TCP_PASS and PGA_TCP_DB parameters respectively located in the E dg4appc admin initsid ora for Microsoft Windows and SORACLE_HOME dg4appc admin initsid ora for UNIX based systems Populating the PGA_TCP_IMSC Table Table 6 1 describes the parameter information contained in the column names types and contents column found in the PGA_TCP_IMSC table Table 6 1 PGA_TCP_IMSC Tabl
42. beginning of a PGAU GROUP PGAU rolls back to the savepoint upon any PGAU command or group failure 2 2 Oracle Database Gateway for APPC User s Guide Definitions and Generation in PGAU You can code COMMIT or ROLLBACK commands within PGAU scripts or interactively in PGAU but not within a GROUP Neither COMMIT nor ROLLBACK is issued for PGAU GENERATE or REPORT commands For information about grouping PGAU commands together to roll back changes in case of failure refer to the discussion of the PGAU GROUP command on page 2 18 later in this chapter Invoking PGAU Before you can invoke PGAU your Oracle database should already be set up If it is not refer to the chapter on configuring your Oracle Database Gateway for APPC in the Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows or Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 Before executing PGAU you must set the ORACLE_HOME environment variable to the directory into which the gateway server was installed If you want to receive PGAU messages in a language other than English set the LANGUAGE environment variable to the appropriate value PGAU is invoked by entering the pgau command You can run prepared scripts of PGAU commands directly from the operating system prompt by
43. calls and data definitions without any change to the RHT APPC Conversation Sharing Concepts Mainframe OLTPs such as IMS allow transactions to share a single APPC conversation by passing it when the transaction calls another transaction RHTs are defined to PGAU as single transactions with calls inputs and outputs for which PGAU generates a single TIP with initialization transfer and termination functions corresponding to that specific RHT Logic generated into every TIP allows that TIP either a toinitiate a new conversation when its init function is called or to transfer data on an existing conversation when its user defined functions are called or to terminate an existing conversation when its term function is called An APPC conversation is treated as a resource shared and managed by multiple TIPs There is no requirement for any TIP to be the sole user of an APPC conversation Any TIP generated at 3 4 0 or later can perform any of the following combinations of service a initiate a initiate and transfer a initiate transfer and terminate standard operation a transfer a transfer and terminate a terminate a initiate and terminate assumes other TIPs perform transfer A single APPC conversation can be shared in the following ways a from one TIP to multiple RHTs from multiple TIPs to one RHT from multiple TIPs to multiple RHTs Without APPC conversation sharing a single TIP must be defined which cont
44. client application on gateway using TCP IP 7 1 calling RPC functions 5 5 component of commit confirm architecture 5 5 interaction with gateway server in commit confirm 5 5 simple communication on gateway using TCP IP 1 14 steps to communication between server and IMS 1 15 Oracle Net 1 5 4 27 7 16 C 1 restrictions for data conversion C 1 overrides 4 18 7 12 LOGMODE 4 18 7 12 LUname 4 18 7 12 Side profile 4 18 7 12 TPname 4 18 7 12 P package UTL_PG 3 1 parameters mapped to TPC IP 6 2 see PGAU commands See remote procedural call RPC See SET LOG_DESTINATION See SET TRACE_LEVEL persistent socket transaction type for TCP IP for IMS Connect 1 14 persistent transaction type for gateway using SNA 1 10 persistent transactions 4 5 4 7 4 8 5 4 PG DD Data Dictionary 2 2 2 10 active dictionary A 5 sequence numbers A 6 versioning A 6 active dictionary tables pga_call A 9 pga_call_parm A 10 pga_data A 11 pga_data_attr A 13 pga_data_values A 14 pga_fields A 12 pga_trans A 6 pga_trans_attr A 7 pga_trans_calls A 9 pga_trans_values A 8 data definitions for parameters over 32K in length D 2 datatype conversion support for COBOL D 2 definition 1 5 definition names valid characters in 2 4 diagnostic options 8 2 references 8 2 entries creating a TIP 3 6 environment dictionary tables A 1 A 2 pga_modes A 5 pga_usage A 5 in writing PGAU statements 3 4 keyword form in stor
45. commit confirm 5 2 Oracle Database Gateway for APPC User s Guide Components Required to Support Commit Confirm transaction log similar to the Oracle two phase commit log stored in the DBA_ 2PC_PENDING table The gateway s transaction log is stored in the PGA_CC_ PENDING table A row is stored in this table for each in flight transaction and remains there until the transaction has completed The life span of rows in PGA_ CC_PENDING is normally quite short lasting only from the time the commit is received by the gateway until the time the Oracle database completes all commit processing and tells the gateway to forget the transaction The commit confirm gateway SID should be reserved for use only to invoke update transactions that implement commit confirm There is some extra overhead involved in the setup for logging when PGA_CAPABILITY is set to COMMIT_CONFIRM Read only transactions should be invoked through a separate gateway SID with PGA_CAPABILITY set to READ_ONLY so that they will not incur the extra overhead Logging Server An Oracle database must be available for use by the gateway server for storing the PGA_CC_PENDING table For maximum performance and reliability Oracle recommends that this Oracle database reside on the same system as the gateway server OLTP Commit Confirm Transaction Log A commit confirm transaction log database must be de
46. components 5 2 logic flow 5 5 step by step 5 6 Oracle Global Transaction ID 5 2 purpose 5 1 relation to two phase commit 5 1 required components logging server 5 3 OLTP commit confirm transaction log 5 3 OLTP forget recovery transaction 5 3 OLTP transaction logging code 5 3 supported OLTPs 5 2 transaction log 5 7 communication between mainframe and Oracle database on gateway using SNA 1 10 between server gateway and remote host 1 8 compiling a TIP 3 7 CONNECT command 2 3 2 6 control file creating on gateway using SNA 1 12 on gateway using TCP IP 1 17 conversation sharing see APPC conversation sharing creating a TIP detailed 3 1 overview 1 12 1 17 D data conversion errors 8 4 DATA correspondence 4 10 7 4 data dictionary see PG DD data exchange PGAXFER function 1 9 data format conversion D 1 database link 1 8 datastores gateway access to 1 2 datatype RAW C 1 datatype conversion D 1 COBOL editing symbols D 3 convert length D 1 duplicate names D 9 expected length D 1 format conversion D 5 parameters over 32K in length D 2 PL SQL D 8 naming algorithms D 8 Index 2 receive length D 1 removing support for parameters over 32K in length D 2 See USAGE PASS USAGE ASIS USAGE SKIP and PL SQL Naming Algorithms send length D 1 truncated and non unique names D 9 datatype conversions COBOL symbols interpreted by PGAU D 3 datatypes See PIC X and PIC G DBCS See double
47. correct transmission buffer and uses the correct data length 4 Ensure the client application has declared the correct TIP datatypes used as arguments in the TIP calls 5 Ensure that the client application is calling the TIP functions in the proper sequence init user defined term and that any input data to the RHT is correct Also ensure that if multiple user defined functions exist they are being called in the proper sequence and passed the correct input values if any DBMS_OUTPUT calls can be inserted in the client application to trace its behavior For more information about calling TIP functions in proper sequence refer to the chapter on configuring the Oracle database for first time installations in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows 6 Optionally regenerate the TIP with diagnostic traces included and enable them The following traces are particularly useful data conversion trace 8 8 Oracle Database Gateway for APPC User s Guide Problem Analysis of Data Conversion and Truncation Errors a function entry exit trace gateway exchange trace Refer to Problem Analysis with TIP Runtime Traces on page 8 5 for more information about traces refer also to GENE
48. datatype to be RAW Lengths of renamed fields do not contribute to the overall parameter data length because the original fields dictate the lengths The WHEN item 3 value is an Oracle extension to the data definition as stored in the PG DD This extension exists only in the PGA context and is not valid COBOL syntax The purpose of this extension is to provide a means for the gateway administrator or application developer to specify the criteria by which the redefinition is to be applied For example a record type field is often present in a record and different record formats apply depending on which record type is being processed The specification of which type value applies to which redefinition is typically buried in the transaction programming logic not in the data definition To specify which conversion to perform on redefined formats in the TIP the WHEN criteria was added to PGA data definitions PGAU generates PL SQL nested record declarations which correspond in name and datatype to the subordinate elements covered by the REDEFINES definition The standard PGAU datatype determination described in PIC X Datatype Conversions on page D 2 LEVEL 01 REDEFINE is ignored This permits remote host copybooks to include definitions which REDEFINE other transaction working storage buffers without having to define such buffers in the TIP or alter the copybook used as input for the definition
49. definitions Sample generate transaction generate db2i pkgname pgadb2i pganode pga outfile pgadb2i Step 2 Execute the control file within PGAU Running the control file within PGAU will create PG DD entries for the data call and transaction definitions and will generate the specification files For example pgadb2i pkh and pgadb2i pkb For Microsoft Windows C gt pgau PGAU gt CONNECT lt userid gt lt password gt lt database gt _specification_string gt PGAU gt pgadb2i ctl For UNIX based systems pgau PGAU gt CONNECT lt userid gt lt password gt lt database gt _specification_string gt PGAU gt pgadb2i ctl Step 3 Execute the specification files Running the specification files will create the PL SQL stored procedures Note that the header specification file for example pgadb2i pkh must be run first For Microsoft Windows C gt sqlplus lt userid gt lt password gt lt database_specification_string gt SQL gt pgadb2i pkh SQL gt pgadb2i pkb For UNIX based systems sqlplus lt userid gt lt password gt lt database_specification_string gt SQL gt pgadb2i pkh SQL gt pgadb2i pkb Introduction to Oracle Database Gateway for APPC 1 13 Overview of a Gateway Using TCP IP Step 4 Create a driver procedure to run the TIP The TIP is now ready for use For convenience it will usually be called using a driver procedure for example db2idriv This driver will then call
50. discusses the generated TIP content file Granting Privileges for TIP Creators Every TIP developer requires access to the following PL SQL packages which are shipped with the Oracle database For Microsoft Windows DBMS _PIPEin SORACLE_HOME rdbms admin a UTL_RAWin SORACLE HOME rdbms admin a UTL_PGin SORACLE_HOME rdbms admin For UNIX based systems m DBMS _ PIPE in SORACLE_HOME rdbms admin a UTL_RAWin SORACLE_HOME rdbms admin E a UTL_PGin SORACLE_HOME rdbms admin If anyone other than user PGAADMIN will be developing TIPs they will need explicit grants to perform these operations Refer to the Optional Configuration Steps section Creating a TIP 3 1 Evaluating the RHT in the configuration chapter appropriate to your communication protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows or more information about private and public grants Evaluating the RHT Follow the steps below to identify and become familiar with your remote host transaction data exchanges Identify the Remote Host Transaction You must first identify the RHT data exchange steps These are the send and receive calls embedded within the RHT program I
51. exchanged in calls with the remote transaction PASS indicates that the item should be translated and exchanged with the transaction ASIS indicates the item is binary and though exchanged should not be translated SKIP indicates the item should be deleted from all exchanges The default value PASS is assumed if this parameter is omitted The USAGE NULL keyword on DEFINE or REDEFINE DATA PGAU statements is not supported is an optional parameter It specifies the compiler options used when compiling the data definition on the remote host The only option currently supported is TRUNC BIN Note that the options must be enclosed in apostrophes or quotes TRUNC BIN is a COBOL option that affects the way halfword and fullword binary values are handled Refer to DEFINE DATA Usage Notes on page 2 9 for further information on this option is a mandatory parameter It specifies the name of the programming language in the supplied definition PGAU presently supports only COBOL 2 8 Oracle Database Gateway for APPC User s Guide PGAU Commands Table 2 2 Cont DEFINE DATA Parameter Descriptions Parameter Description definition is mutually exclusive with the INFILE parameter Itis an inline description of the data The description must be provided in COBOL syntax as indicated above This inline description must begin with an opening pa renthesis and end with a c
52. flipmain pkgcall pgtflip_main parms flipin in flipout out 3 DEFINE TRANSACTION This is used to group the preceding functions and specify other parameters on which the TIP depends a Sample define transaction define transaction imsflip call flipmain sideprofile pgatcp tpname flip nls_language american_america us7ascii Note Ona gateway using TCP IP the side profile name value is actually the TCP IP unique name that was defined when the user specified the value host name port number and many other IMS Connect values during configuration of the network 4 GENERATE This is used to generate the TIP specification files from the previously stored data call and transaction definitions Sample generate transaction generate imsflip pkgname pgtflip pganode pgal0ia outfile pgtflip diagnose pkgex dc dr Step 2 Execute the control file within PGAU Running the control file within PGAU will create PG DD entries for the data call and transaction definitions and will generate the specification files for example pgtflip pkh and pgtflip pkb For Microsoft Windows C gt cd ORACLE_HOME dg4appc demo IMS C gt pgau PGAU gt CONNECT userid password database_specification_string PGAU gt pgtflip ctl For UNIX based systems pgau 1 18 Oracle Database Gateway for APPC User s Guide Overview of a Gateway Using TCP IP PGAU gt CONNECT userid passwordtdataba
53. for more examples and Appendix E Tip Internals for more information DIAGNOSE is an optional parameter with two options TRACE and PKGEX TRACE specifies that an internal trace of the execution of PGAU is written to output file pgau tre in the user s current directory TRACE suboptions are delimited by commas Trace messages are provided as a diagnostic tool to Oracle Support Services and other Oracle representatives to assist them in diagnosing customer problems when generating TIPs They are part of an Oracle reserved function for which the usage interface and documentation might change without notice at Oracle s sole discretion This information is provided so customers might document problem symptoms a SE Subroutine Entry Exit Messages are written tracing subroutine name and arguments upon entry and subroutine name and conditions at exit IT Initialization Termination Messages are written tracing PGAU initialization and termination functions QM Queue Management Messages are written tracing control block allocation queuing searching dequeuing and deletion a IO Input Output Messages are written tracing input output and control operations for dat input files and wrk and package output files 2 16 Oracle Database Gateway for APPC User s Guide PGAU Commands Table 2 5 Cont GENERATE Parameter Descriptions Parameter Description PKGEX a DD PG DD De
54. for more information about the function and use of these parameters You can initiate an IMS TM transaction that executes static SOL in DB2 This illustrates the power of the Oracle Database Gateway for APPC s feature supporting TCP IP for IMS Connect Simple Gateway Communication with the Oracle Database TCP IP This section describes simple communication between IMS and the Oracle database whenTCP IP for IMS Connect is being used as the communication protocol between 1 14 Oracle Database Gateway for APPC User s Guide Overview of a Gateway Using TCP IP the gateway and the remote host IMS The Oracle Database Gateway for APPC lets you write your own procedures to begin transferring information between the Oracle database and I O PCB programs on IMS For an illustration of the communications function of the gateway using TCP IP for IMS Connect refer to the SORACLE_HOME dg4appc demo IMS pgaims sq l file on Microsoft Windows or SORACLE_HOME dg4appc demo IMS pgaims sql on UNIX based systems Executing the simple PL SQL procedure pgaims sql causes the Oracle database to call the gateway which uses TCP IP to converse with the sample transaction FLIP in IMS The communication steps that take place when you execute the PL SQL procedure are described in detail in Section Steps to Communication Between the Gateway and IMS Using TCP IP Note that you will already have compiled and linked the stored procedure wh
55. gateway PGAU nor generated TIPs provide this synchronization but they will issue messages as error conditions are detected Data definitions must exist before being referenced by call definitions Call definitions must exist before being referenced by transaction definitions Note It is your responsibility to ensure that the data transaction definition versions that are stored and used in the PG DD are synchronized with the remote transactions The gateway PGAU and generated TIPs do not provide this synchronization but issue messages as error conditions are detected Process to Define and Test a TIP The general process for defining and testing a TIP for a given transaction is as follows 1 Define input and output using COBOL data definitions 2 Redefine the default datanames and PL SQL variable names created by the above process optional 3 Define PL SQL FUNCTION calls to be generated as part of the PL SQL package 4 Define a transaction that groups the above functions 5 Generate the TIP specifications from the previously stored TRANSACTION CALL and DATA definitions 6 Generate the TIP PL SQL stored procedures 7 Test the TIP by calling it from a high level application Refer to Chapter 3 Creating a TIP for more information about TIPs Definition Names Definition names are unique identifiers that you designate through PGAU The name is a string of 1 to 30 bytes If punctuation or white spac
56. gateway issues TCP IP receive receive completes calls tip_term Call PGATERM Gateway issues TCP IP close A client application which utilizes the gateway to exchange data with a remote host transaction performs some tasks for itself and instructs the TIP to perform other tasks on its behalf The client application designer must consequently know the behavior of the remote transaction and how the TIP facilitates the exchange The following sections provide an overview of remote host transaction behavior how this behavior is controlled by the client application and how TIP function calls and data declarations support the client application to control the remote host transaction 7 2 Oracle Database Gateway for APPC User s Guide Preparing the Client Application These sections also provide background information about what the TIP does for the client application and how the TIP calls exchange data with the remote host transaction Preparing the Client Application To prepare the client application for execution you must understand the remote host transaction requirements and then perform these steps 1 Make sure that the pg4tcpmap tool has been used to map the SIDEPROFILE name defined in the ct 1 file for the PGAU utility to TCP IP and IMS Connect attributes Refer to Chapter 6 PG4TCPMAP Commands TCP IP Only in this guide for detailed information about mapping parameters 2 Make certain that
57. gateway server calls the logging server to insert and delete rows from its PGA_ CC_PENDING table This is actually done by calling a PL SQL stored procedure PGA_CC_LOG in the logging server to reduce the number of open cursors required by the gateway server for performing its logging Only a single cursor is needed by the gateway server for logging Commit Confirm Flow The flow of control for a successful commit between an Oracle application and an OLTP transaction is described in the following section and illustrated in Figure 5 1 Commit Confirm Flow with Synclevel 1 The figure assumes that both Oracle and OLTP resources have been updated The following steps in Section outline the commit confirm logic flow Implementing Commit Confirm SNA Only 5 5 Commit Confirm Flow Commit Confirm Logic Flow Step by Step 1 2 10 11 12 13 14 15 16 The application issues a COMMIT to the Oracle database The Oracle database sends PREPARE to each participant in the distributed transaction other than the gateway Each participant prepares its database updates and responds PREPARE OK to the Oracle database The Oracle database sends COMMIT to the gateway The gateway receives the COMMIT from the Oracle database and inserts a new pending transaction row into the PGA_CC_ PENDING table The gateway sends an APPC CONFIRM to the OLTP application The OLTP application receives the C
58. in a conventional Oracle database It is installed by a SOL Plus installation script pyddcr8 sql in the SORACLE_HOME Ydg4appcradmin directory on Microsoft Windows or SORACLE_HOME dg4appc admin directory on UNIX based systems and manipulated by PGAU statements and standard SQL statements The dictionary is divided into two sections a the environment dictionary the active dictionary The environment dictionary is static and should not be changed The contents of the environment dictionary support proper translation from the remote transaction s environment to the integrating server s environment and is platform specific The active dictionary is updated at the user s location by the PGAU in response to definitions supplied by the user PG DD Environment Dictionary The PGAU uses some dictionary tables strictly as input These dictionary tables define environmental parameters for PGAU Both table and values are installed by a SQL Plus script at gateway installation time and are not to be modified by the installation The environment dictionary does not reference the active dictionary but the active dictionary does reference environment dictionary entries Environment Dictionary Sequence Numbers The environment dictionary requires unique identifying numbers in some columns to join environment dictionary entries together Oracle sequence objects are therefore created by the Oracle Database Gateway for APPC to support this requir
59. is the TIP s mechanism for routing the client application call through the gateway to the intended remote transaction program It is the responsibility of the client application to save 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 initialization function as if it were any local PL SQL function For example trannum INTEGER 0 transaction usage number BEGIN rc pgtflip pgtflip_init trannum Overriding TIP Initializations Note that in the preceding example the client application did not specify any remote transaction program name network connection or security information The TIP has such information internally coded as defaults and the client application simply calls the appropriate TIP for the chosen remote transaction program The client application can however optionally override some TIP defaults and supply security information You do not need to change any client applications that do not require overrides Client Application Development TCP IP Only 7 11 Calling the TIP from the Client Application When the remote host transaction was defined in the PG DD the DEFINE TRANSACTION statement specified certain default OLTP and network identification attributes which can be overridden TPname a Side Profile Refer to DEFINE TRANSACTION in Chapter 2 Procedural Gat
60. item is NULL charval varchar2 40 Attribute s character value fname for RENAMEMF renames first fname for RENAMEML renames last fname for REMAPSMF redefines first fname for REMAPSML redefines last fname for REMAPSWM redefines when fname for REPGRPVM odo member string for REMAPSWC redefines string for REPGRPKA occurs key string for REPGRPKD occurs key string for REPGRPIX occurs index string for PLSTYPE PL SQL data type string for JUST string for SYNC string for REMOTE_LANGUAGE fname for LENGTH If a non character attribute this item is NULL Max length gt NLS_charset string length dateval date Attribute s date value Always null included for completeness qual number Qualified name number 9 0 Foreign key Database Gateway for APPC Data Dictionary A 15 PG DD Active Dictionary A 16 Oracle Database Gateway for APPC User s Guide Gateway RPC Interface To execute a remote transaction program using the Oracle Database Gateway for APPC you must execute a PL SOL 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 an
61. name 2 11 simple DG4APPC communication on gateway using SNA 1 10 SNA and gateway components 1 7 communication between mainframe and Oracle database 1 10 communications function 1 11 creating a TIP 1 12 determining validity of TIP specification E 2 examples and sample files used in this guide 1 6 flexible call sequence 4 12 function in the gateway 1 1 gateway transaction types 1 10 implementing commit confirm 5 1 overview of the gateway using 1 1 Index 8 parameters 1 9 PGAU DEFINE TRANSACTION command 3 3 remote transaction initiation 1 9 remote transaction termination on the gateway 1 9 steps to connecting Oracle database and mainframe 1 11 supported remote host languages 3 2 TIP internals E 1 uses APPC to access all systems 1 2 writing TIPs 1 12 socket file descriptor returned by TCP IP network to PGAINIT 1 9 specification file on gateway using SNA 1 13 on gateway using TCP IP 1 18 SPOOL command 2 28 SQL Plus connecting server and mainframe 1 11 invoking 3 7 recompiling TIP body changes E 2 running scripts 4 27 7 16 test scripts 8 3 statements see PGAU commands SYNCHRONIZED D 8 SYNCHRONIZED LEFT D 8 SYNCHRONIZED RIGHT D 8 T TCP IP for IMS Connect 1 15 7 11 and gateway components 1 7 and PGA_TCP_IMSC parameter table 6 1 and PGAINIT 6 1 and Remote Transaction Initiation 1 9 Client application overview 7 1 communication between gateway and Oracle database 1 14 content o
62. of how to intercept and handle Oracle exceptions Granting Execute Authority The TIP is a standard PL SQL package and execute authority must be granted to users who call the TIP from their client application In this example we grant execute on the pgtflip package to user SCOTT GRANT EXECUTE ON PGTFLIP TO SCOTT Refer to the Oracle Database Administrator s Guide for further information Calling PG4TCPMAP PGAU need not be modified in order to have a conversation on a gateway using TCP IP You use the APPC format of PGAU but you will map parameters to TCP IP using the pg4tcpmap tool To map the DEFINE TRANSACTION parameters using TCP IP you must have a valid input within the PGA_TCP_IMSC table before executing the application Refer to Chapter 6 PG4TCPMAP Commands TCP IP Only for information about setting up and using the mapping tool Executing the Application Before executing the client application ensure that a connection to the host is established and that the receiving partner is available In this example we use PL SQL driver PGTFLIPD to execute the IMS IMS Connect inquiry To execute this client application enter from SQL Plus set serveroutput on execute pgtflipd hello 7 14 Oracle Database Gateway for APPC User s Guide Application Development with Multi Byte Character Set Support Application Development with Multi Byte Character Set Support COBOL presently only supports doubl
63. of the PG DD USAGI OG PASS ASIS is optional If omitted the last usage specified is retained It specifies the way the TIP handles the data items when exchanged in calls with the remote transaction SKIP PASS indicates that the item should be translated and exchanged with the transaction ASIS indicates the item is binary and though exchanged should not be translated n SKIP indicates the item should be deleted from all exchanges If specified all affected fields are updated with the same USAGE value Refer to the notes pertaining to single or multiple field redefinition under FIELD The USAGE NULL keyword on DEFINE or REDEFINE DATA PGAU statements is not supported COMPOPTS options is optional If omitted the last options specified are retained If specified as a null string then the last options specified are removed If a non null value is specified then the last options specified are all replaced with the new options The only option currently supported is TRUNC BIN Note that the options must be enclosed in apostrophes or quotes TRUNC BIN is a COBOL option that affects the way halfword and fullword binary values are handled Refer to REDEFINE DATA Usage Notes on page 2 22 for further information on this option REMOTE_LANGUAGE is an optional parameter The default value is nlsname american_america we8ebcdic37c or as overrid
64. process control computer a You can initiate an IMS TM transaction that executes static SQL in DB2 a You can initiate a CICS transaction that returns a large number of records in a single call Simple Gateway Communication with the Oracle Database SNA This section describes simple communication between the mainframe and the Oracle database on a gateway using the SNA communication protocol The Oracle Database Gateway for APPC lets you write your own procedures to begin transferring information between the Oracle database and a variety of programs on an IBM mainframe including IBM CICS IMS and APPC MVS For an illustration of the communications function of the Oracle Database Gateway for APPC refer to SORACLE_HOME dg4appc demo CICS pgacics sql on Microsoft Windows or SORACLE_HOME dg4appc demo CICS pgacics sql on UNIX based 1 10 Oracle Database Gateway for APPC User s Guide Overview of a Gateway Using SNA platforms This is a sample communication between the Oracle database and CICS Transaction Server for z OS Executing this simple PL SQL procedure pgacics sql causes the Oracle database to invoke the database gateway which uses SNA to converse with the FLIP transaction in CICS These steps are described in detail in Section Steps to Communicate Between Gateway and Mainframe Using SNA Note that you will already have compiled and linked the stored procedure when you configured the gateway St
65. program RTP residing on a host The gateway provides RPC processing to systems using the SNA Advanced Program to Program Communication APPC protocol and to IMS TM systems using TCP IP support for IMS Connect This architecture allows efficient access to data and transactions available on the IBM mainframe and IMS respectively Introduction to Oracle Database Gateway for APPC 1 1 Features of the Gateway The gateway requires no Oracle software on the remote host system Thus the gateway uses existing transactions with little or no programming effort on the remote host For gateways using SNA only The use of a generic and standard protocol APPC allows the gateway to access numerous systems The gateway can communicate with virtually any APPC enabled system including IBM Corporation s CICS on any platform and IBM Corporation s IMS and APPC MVS These transaction monitors provide access to a broad range of systems allowing the gateway to access many datastores including VSAM DB2 static SQL IMS and others The gateway can access any application capable of using the CPI C API either directly or through a TP monitor such as CICS Features of the Gateway The Oracle Database Gateway for APPC provides the following benefits Fast interface The gateway is optimized so that remote execution of a program is achieved with minimum network traffic The interface to the gateway is an optimized PL SQL stored procedure specification
66. role 1 9 Remote Transaction Termination eseese eiliset Ankenia ESKER AEE AEREE ES 1 9 Overview of a Gateway Using SNA ooonicicicicionnnnnncncononncnoncncononnnnanoncororoncn nono ro rancia ro ran nro re rancios 1 10 Transaction Types for a Gateway Using SNA cccccccscssssesesceceseseseeneneneseecenesesesanenesessanensneeans 1 10 Simple Gateway Communication with the Oracle Database SNA connnicicncncononicinininnananocnoos 1 10 Steps to Communicate Between Gateway and Mainframe Using SNA cnconcnccninnncnnnnnnnos 1 11 Writing TIPs to Generate PL SQL Programs Using SNA oncicicicinononcononononinonaninnnnnncnoninananonono 1 12 Steps to Writing a TIP on a Gateway Using SNA occcnonincnoncncnnnonncnnnnonononcnnnnnnnoncnnnnnnncncncnns 1 12 Overview of a Gateway Using TCP TP o oononicicicinonicinnnncncncnnonornnnoncnnorornn cinco raro ran cinco ro ron cocinar rancios 1 14 Transaction Types for a Gateway Using TCP IP oooconcncococicinannnnonencnnrananennrrnnecncnnnrnrnararnnnnnnnnass 1 14 Simple Gateway Communication with the Oracle Database ICP TP occonicincncononininnnninannnnoos 1 14 Preparing the Gateway to Communicate Using TCP TPoooonocncononeninoononsnnnnrenrnmerrnos 1 15 Steps to Communication Between the Gateway and IMS Using TCP IP ooococinincccnonn 1 15 Writing TIPs to Generate PL SQL Programs Using TCP IP ooonocicicicicinononinnnnnnennncnnonincnnnonoso 1 17 Steps to Writing a TIP on a Gateway Using TCP IP ooooneconiccncononennnnnnnenn
67. s requirements for each remote transaction program The Transaction Interface Package provides this customized interface Example Assume that the remote site has a transaction program which manages employee information in an employee database or other file system The remote transaction program s name in the remote host is EMPT for Employee Tracking EMPT provides both inquiry and update facilities and different Oracle users are required to access and use these EMPT facilities Some users might be restricted to inquiry only use of EMPT while others might have update requirements In support of the Oracle users client applications at least three possible TIPs could exist 1 EMP_MGMT to provide access to all facilities of the EMPT remote transaction program 2 EMP_UPDT to access only the update functions of the EMPT remote transaction program 3 EMP_INQR to access only the lookup functions of the EMPT remote transaction program End user access to these TIPs is controlled by Oracle privileges Additional security might be imposed on the end user by the remote host Each TIP also has encoded within it the name of the remote transaction program EMPT and network information sufficient to establish an APPC conversation with EMPT Client Application Requirements Using the TIP the client application must correspond with and control the remote host transaction This involves 1 client
68. such as PGAXFER and PGATERM use this same socket file descriptor as an input parameter Data Exchange After the conversation is established a database gateway function called PGAXFER can exchange data in the form of input and output variables PGAXFER sends and receives buffers to and from the target transaction program The gateway sees a buffer as only a RAW stream of bytes The TIP that resides in the Oracle database is responsible for converting PL SQL datatypes of the application to RAW before sending the buffer to the gateway It is also responsible for converting RAW to PL SQL datatypes before returning the results to the application Remote Transaction Termination When communication with the remote program is complete the gateway function PGATERM terminates the conversation between the gateway and the remote host When the communication protocol is SNA PGATERM uses the conversation identifier as an input parameter to request conversation termination When the communication protocol is TCP IP PGATERM uses the socket file descriptor for TCP IP as an input parameter to request conversation termination Introduction to Oracle Database Gateway for APPC 1 9 Overview of a Gateway Using SNA Note At this point if your communication protocol is SNA then proceed to the following section Section Overview of a Gateway Using SNA on page 1 10 If your gateway communication protocol is TCP
69. supplied by the sending remote host transaction all data conversion to PL SQL OUT parameters supplied by the sending remote host transaction PGAU determines the information needed to generate the conversion and buffering logic from the data definitions included in the remote host transaction program PGAU DEFINE DATA reads this information from files such as COBOL copy books or in stream from scripts and saves it in the PG DD for repeated use The gateway Administrator needs to transfer these definition files from the remote host to the Oracle host where PGAU runs 4 10 Oracle Database Gateway for APPC User s Guide Ensuring TIP and Remote Transaction Program Correspondence From the data definitions stored in the PG DD PGAU GENERATE determines the remote host datatype and matches it to an appropriate PL SQL datatype It also determines data lengths and offsets within records and buffers and generates the needed PL SQL logic into the TIP Refer to the PGAU DEFINE DATA statement on page 2 2 in Chapter 2 Procedural Gateway Administration Utility and Sample PGAU DEFINE DATA Statements in Appendix F Administration Utility Samples for more information All data that are referenced as parameters by subsequent calls must first be defined using PGAU DEFINE DATA Simple data items such as single numbers or character strings and complex multi field data aggregates such as records or structures can be defined PGAU au
70. the transaction are encoded Examples Refer to Sample PGAU DEFINE TRANSACTION Statement in Appendix F for examples of DI EFINE TRANSACTIONS commands DEFINE TRANSACTION Usage Notes NLS_LANGUAGE and the Oracle database s LANGUAGE specify default character sets to be used for conversion of all single byte character fields for the entire transaction These defaults can be overridden for each SBCS field by the REDEFINE DATA REMOTE_LANGUAGE or LOCAL_LANGUAGE parameters a The version of the TRANSACTION definition is not specified and defaults to NEXTVAL of the Oracle Sequence Object for TRANS REMOTE_MI BCS and LOCAL_MBCS specify the default multi byte character sets to be used for conversion of all DBCS or MBCS fields for the entire transaction This 2 12 Oracle Database Gateway for APPC User s Guide PGAU Commands DESCRIBE DISCONNECT default can be overridden for each DBCS or MBCS field by the REDEFINE DATA REMOTE_LANGUAGE or LOCAL LANGUAGE parameters a You must place at the end of the command Purpose Use this command to describe a table view stored procedure or function If neither TABLE VIEW nor PROCEDURE are explicitly specified the table or view with the specified name is described Syntax The DESCRIBE command has the following syntax DESCRIBE TABLE table VIEW view PROCEDURE proc some_name Parameter
71. 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 initialization function as if it were any local PL SQL function For example tranuse INTEGER 0 transaction usage number BEGIN rc pgadb2i pgadb2i_init tranuse Overriding TIP Initializations Note that in the preceding example the client application did not specify any remote transaction program name network connection or security information The TIP has such information internally coded as defaults and the client application simply calls the appropriate TIP for the chosen remote transaction program The client application can however optionally override some TIP defaults and supply security information You do not need to change any client applications that do not require overrides Client Application Development SNA Only 4 17 Calling the TIP from the Client Application When the remote host transaction was defined in the PG DD the DEFINE TRANSACTION statement specified certain default OLTP and network identification attributes which can be overridden C TPname m LUname a LOGMODE a Side Profile Refer to DEFINE TRANSACTION in Chapter 2 Procedural Gateway Administration Utility for more information about the DEFINE TRANSACTION statement These PG DD defined transaction attributes are generated into TIPs
72. warning is issued when the expected length of a received parameter does not equal its convert or received length and data conversion tracing is enabled This occurs when a maximum length record is expected but a shorter record is transmitted and correctly converted Datatype Conversions D 1 Conversion Parameters Over 32K in Length Conversion USAGE PASS PGAU generates TIPs that support transmission of individual data parameters which exceed 32K bytes PGAU includes this support automatically when PGAU GENERATE processing detects the maximum length of a data parameter exceeding 32K This support is driven by the data definitions placed in the PG DD and cannot be selected by the user To include the support the data definition must actually or possible exceed 32K To remove the support you must decrease the parameter length to less than 32K REDEFINE the data and GENERATE the TIP again This support tests for field positions crossing the 32K buffer boundaries before and after conversion of those fields which lie across such boundaries In the case of repeating groups This can be many fields for repeating groups or few fields in the case of simple linear records Each test and the corresponding buffer management logic adds overhead Caution The target of a REDEFINE clause cannot reside in a previously processed buffer Run time TIP processing of the fields con
73. with the item to be dropped If no version is specified only the latest highest numbered version is removed VERSion datavers An optional parameter It specifies which singular version of a definition is to be removed or if ALL then all definitions are removed for the given definition named The default of the transvers ALL highest numbered version of the named definition is assumed if VERSION is omitted callvers Examples Refer to Sample PGAU UNDEFINE Statements in Appendix F for examples of UNDEFINE DATA commands UNDEFINE DATA Usage Notes a Removing definitions only prevents PL SQL packages TIPs from being subsequently generated Previously generated TIPs can still be recreated if the pkh and pkb specification files remain in existence Previously created TIPs can still be invoked if they remain in the database of the Oracle database Whether such TIPs execute successfully depends on whether the corresponding remote transaction programs are still active Remove a DATA definition only after all CALLs and all TRANSACTIONs which reference it are removed No integrity checking is done wan a You must place at the end of the command UNDEFINE TRANSACTION Purpose This command removes an occurrence of the TRANSACTION definition in the PG Data Dictionary Syntax UNDEFINE TRANSACTION tname VERSion tranvers ALL Parameters Table 2 12 describes the UNDEFINE TRANSACTION par
74. 1 preparation 4 3 remote host transaction types multi conversational transactions 4 5 one shot transactions 4 4 persistent transactions 4 5 See also index entries for each transaction type requirements 4 6 declare RHT TIP data to be exchanged 4 7 4 8 4 9 exchange data with RHT using TIP user function 4 7 4 9 initialize RHT for multi conversational applications 4 9 initialize RHT using TIP initialization function 4 7 4 8 repetitively exchange data with RHT using TIP user function 4 8 terminate RHT using TIP termination function 4 7 4 8 4 9 security considerations 4 19 7 13 terminating the conversation 4 19 7 13 TIP and remote transaction program correspondence 4 10 7 4 TIP CALL correspondence 4 11 TIP content and purpose 4 3 TIP DATA correspondence 4 10 7 4 TIP TRANSACTION correspondence on gateway using SNA 4 13 on gateway using TCP IP 7 7 client application development for gateway using TCP IP overview 7 1 client application development on gateway using TCP IP preparing 7 3 COBOL 4 3 7 3 D 2 D 8 datatype conversion supported by PG DD and TIPs D 2 lacks datatype for variable length data D 2 PGAU interpretation of COBOL symbols D 3 support for double byte character sets PIC G Index 1 datatypes 4 25 7 15 COMMIT command 2 2 2 3 user responsibility 2 2 COMMIT processing 2 2 commit confirm 5 2 application design requirements 5 4 architecture 5 4 components 5 5 interactions 5 5
75. 1 of the Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows to learn more about how to set the RACF userid and RACF password IRM_ID char 8 NOT Specifes the IMS Connect user exit NULL IRM ID If you do not specify this parameter it will default to IRMREO corresponding to the IBM HWSIMSOO sample user exit LULL char 1 NOT Specifies whether the IMS Connect NULL user exit return data includes the LLL total length prefix field or not Supported values are Y the exit return data includes the iL prefix field N the exit return data does not include the LLLL prefix field The default value is N Before You Run the pg4tcpmap Tool Follow these steps to prepare for running the pg4tcpmap tool before you run the gateway 1 Set the ORACLE_HOME and ORACLE_SID for the Oracle database 2 Make certain that the user PEAADMIN has been created in the Oracle database and you can talk to the database Issue SORACLE_HOME dg4appc admin pgacr8au sql on Microsoft Windows 6 4 Oracle Database Gateway for APPC User s Guide Before You Run the pg4tcpmap Tool Or SORACLE_HOME dg4appc admin pgacr8au sql on UNIX based systems The initsid ora file must contain appropriate parameters Set the following parameters PGA_TCP_USER PGA_TCP_PASS PGA_TCP_DB If you intend to enable the tracing you will also need to set the following par
76. 14 Oracle Database Gateway for APPC User s Guide PGAU Commands GENERATE Purpose A PL SQL package is built and written to the indicated output files The PG Data Dictionary is not updated by this command Sy ntax GENERATE tname VERSion tranvers PKGNAME pname PGANODE dblink_name OUTFILE specpath specname spectype bodypath bodyname bodytype DIAGNOSE TRACE SE IT QM 10 0C DD TG PKGEX DC DR Parameters Table 2 5 describes the GENERATE parameters Table 2 5 GENERATE Parameter Descriptions Parameter Description tname is a mandatory parameter It is the transaction name PKGNAMI defined ina DEFINE TRANSACTION statement VERSion transvers is an optional parameter It specifies which transaction definition is to be used The VERsion parameter defaults to highest numbered transaction if not specified 53 pname is an optional parameter It specifies the name of the PL SQL package to be created If this operand is omitted the package name is assumed to be the same as the transaction name T PGANODE dblink_name is an optional parameter It specifies the Oracle database link name to the gateway server If this operand is omitted PGA is assumed to be the dblink_name OUTFILE is an optional parameter If this parameter is specified specname must also be specified spe
77. 2 UTL_RAW PL SQL package 3 1 C 1 definition 1 4 V VARIABLE command 2 31 W WMSG function C 10 WMSGCNT function C 9 writing PGAU statements 3 4
78. 3 an existing definition No attempt is made by PGAU to synchronize versions Although the existence of dependent items is assured at definition time deletion is done without reference to dependencies For example generating a TIP requires prior definition of the transaction which requires prior definition of the calls which require prior definition of the data But nothing prevents PGAU from deleting an active data definition while a call definition still references it All PGAU keywords can be specified in upper or lower case and are not reserved words Reservation is not necessary because all keywords have known spelling and appear in predictable places and because all data is delimited by parentheses apostrophes quotes or blanks Procedural Gateway Administration Utility 2 5 PGAU Commands Note that all unquoted values specified by keywords are stored in the PG Data Dictionary in uppercase unless otherwise specified in the keyword description PGAU Commands PGAU allows you to enter Procedural Gateway Administration commands commands such as DEFINE UNDEFINE REDEFINE and GENERATE in addition to normal SQL commands The SET and SHOW commands are also implemented In addition the PGAU commands listed in the following section are available to you CONNECT Purpose This command enables you to make a connection to PGAU Use the CONNECT command to log on to an Oracle database optionally specif
79. 4 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows An example of a trace file from a sample pg4tcpmap execution can be found in Chapter 8 Troubleshooting pg4tcpmap Tool Commands There are two commands for the pg4tcpmap tool a one command inserts a row into the PGA_TCP_IMSC table a the other command deletes a row from the table and the user must specify the predicate as Side Profile Name Inserting a Row into the PGA_TCP_IMSC Table For Microsoft Windows issue the following command from the gateway Oraclehome SORACLE_HOME bin directory C gt pg4tcpmap For UNIX based systems issue the following command from the gateway Oracle home SORACLE_HOME bin directory pg4tcpmap The gateway release number copyright information along with the following text appears This tool takes the IMS Connect TCP IP information such as host name and port number and maps them to your TIPs You may use this tool to insert or delete IMS Connect TCP IP information If you want to insert a row Type I If you want to delete a row type D Enter lt i gt and after that you need only enter the required parameters Deleting Rows from the PGA_TCP_IMSC Table For Microsoft Windows issue the following command from the gateway Oracle home SORACLE_HOME bin directory C gt pg4tcpmap
80. 6 PGATRAC parameters B 6 PGAXFER B 4 PGAXFER parameters B 4 remote procedure definition 1 4 remote transaction initiation on gateway using SNA 1 9 on gateway using TC IP 1 9 remote transaction program See RTP remote transaction termination on gateway using SNA 1 9 on gateway using TCP IP 1 9 RENAMES D 7 REPORT statement 3 5 RHT See remote host transactions ROLLBACK command 2 2 2 3 ROLLBACK processing 2 2 RPC definition 1 5 function Index 7 PGAINIT 1 4 1 9 PGATERM 1 4 PGAXFER 1 4 1 9 within the gateway 1 1 1 8 processing 1 1 RPC interface PGATCTL B 6 PGATERM B 5 PGATRAC B 6 PGAXFER B 4 See also remote procedural call RPC RTP activities 4 5 definition 1 5 executing 1 5 function in the gateway 1 1 on gateway using SNA 4 6 purpose 4 4 7 3 runtime traces 8 5 controls 8 6 conversion warnings 8 6 data conversion tracing 8 7 gateway exchange tracing 8 7 runtime function entry exit tracing 8 7 S sample PGAU DEFINE CALL command F 2 PGAU DEFINE DATA command F 1 PGAU DEFINE TRANSACTION command F 2 PGAU GENERATE command F 2 PGAU REDEFINE DATA command F 6 PGAU UNDEFINE command F 7 sample definitions implicit versioning F 3 script file 3 5 sequence objects in the PGDD environment dictionary A 1 SET command 2 26 SET LOG_DESTINATION parameter 8 9 8 10 8 11 SET TRACE_LEVEL parameter 8 9 8 11 8 12 Side Information Profile 2 12 B 3 SIDE_NAME 5 7 SIDEPROFILE
81. 8 Cont SET Parameter Descriptions Parameter Description SERVEROUTPUT OFF ON Sets debugging output from stored procedures that use DBMS_ SIZE n n OUTPUT PUT and PUT_LINE commands to ON or OFF You can specify the size in bytes of the message buffer using SIZE n The size specified is the total number of bytes of all messages sent that can be accumulated at one time The minimum is 2000 bytes If the buffer fills before calls to the get message routines make room for additional message bytes an error is returned to the program sending the message SERVEROUTPUT with no parameters is the same as SERVEROUTPUT ON STOPONERROR ON OFF Indicates whether execution of a command file should stop if an error occurs Specifying OFF disables STOPONERROR TERMOUT ON OFF Enables or disables terminal output for SQL commands It is useful for preventing output to the terminal when spooling output to files The default is OFF which disables terminal output TIMING ON OFF Enables or disables display of parse execute and fetch times both CPU and elapsed for each executed SQL statement The default is OFF which disables the TIMING display Examples PGAU gt set arraysize 30 PGAU gt set CHARWIDTH SET Usage Notes You do not need to place at the end of the command Parameters Table 2 9 describes the SHOW parameters Table 2 9 SHOW Parameter Descriptions
82. 9 0 not null Env id Foreign key comp number 9 0 notnull Compiler env id Foreign key ddl_process number 9 0 notnull PGADDL processor number pga_datatypes The pga_datatypes table stores the datatype keywords as presented in Table A 7 Table A 7 pga_ datatypes Column Type Content comp number 9 0 notnull Compiler env id Primary key name varchar2 16 not Datatype keyword null Primary key dt number 9 0 notnull Datatype_values Foreign key pga_datatype_attr The pga_datatype_attr table stores datatype attribute keywords as presented in Table A 8 Table A 8 pga_datatype_atir Column Type Content name varchar2 16 Attribute keyword not null Primary key attrt number 9 0 not Attribute id null Foreign key coltype varchar2 4 not Type of attr null Foreign key pga_datatype_values The pga_datatype_values table stores the datatype attribute values as presented in Table A 9 Table A 9 pga_datatype_values Column Type Content comp number 9 0 not Compiler env id null Primary key dt number 9 0 not datatype_values null Foreign key A 4 Oracle Database Gateway for APPC User s Guide PG DD Active Dictionary Table A 9 Cont pga_datatype_values Column Type Content attr number 9 0 not Attribute id aja Foreign key dag number 9 0 Datatype attr group no numval number 9 0 Numeric attribu
83. A to a TCP IP communications protocol to invoke IMS transactions You need to regenerate the TIPs Refer to Chapter 2 Procedural Gateway Administration Utility for details Writing the PGAU Statements After evaluating the RHT define the TIP to PGAU for placement in the PG DD 1 Write a DEFINE DATA statement for each entry in your data list If for example your RHT had three different data structures your data definitions might be DEFINE DATA dnamel LANGUAGE IBMVSCOBOLII INFILE dnamel ext DEFINE DATA dname2 LANGUAGE IBMVSCOBOLII INFILE dname2 ext DEFINE DATA dname3 LANGUAGE IBMVSCOBOLII INFILE dname3 ext Then you must copy or transfer the source file containing these data definitions to the directory where PGAU can read them as input 2 Write a DEFINE CALL statement for each entry in your call list If for example your RHT had a receive send receive send sequence your call definitions would be DEFINE CALL cnamel PARMS DEFINE CALL cname2 PARMS DEFINE CALL cname3 PARMS DEFINE CALL cname4 PARMS dnamel IN dname2 OUT dname3 IN dname2 OU i i 3 4 Oracle Database Gateway for APPC User s Guide Evaluating the RHT Note Optionally you can rewrite your call definitions to consolidate the data transmission into fewer exchanges as long as you do not alter the data transmission sequence For example y Thi fou call par
84. AGEs for any individual PIC G data item can be further overridden see REDEFINE DATA REMOTE or LOCAL_ LANGUAGE DBCS data can be encoded in any combination of supported DBCS character sets For example a remote host application which allows different codepages for each field of data in a record is supported by the Oracle Database Gateway MBCS support Client Application Development SNA Only 4 25 Modifying a Terminal Oriented Transaction to Use APPC Use of REDEFINE DATA REMOTE_LANGUAGE or LOCAL LANGUAGE on PIC X items is also supported Thus a TIP can perform DBCS or MBCS conversions for specified PIC X data fields in addition to SBCS conversions by default for the remaining PIC X data fields Default SBCS conversion is according to the DEFINE TRANSACTION NLS_LANGUAGE and local Oracle default LANGUAGE environment values When PGAU is generating a TIP the PIC G datatypes are converted to PL SQL VARCHAR2 datatypes After conversion by the TIP received PIC G VARCHAR2 datatypes can have a length less then the maximum due to deletion of shift out and shift in meta characters and sent PIC G RAWs will have the shift out and shift in characters inserted as required by the remote host character set specified This is different from the conversions performed for PIC X data which is always a known fixed length
85. AP on page 7 14 Executing the Application on page 7 14 Application Development with Multi Byte Character Set Support on page 7 15 a Privileges Needed to Use TIPs on page 7 16 Overview of Client Application The Procedural Gateway Administration Utility PGAU generates a complete TIP using definitions you provide The client application can then call the TIP to access the remote host transaction Chapter 2 Procedural Gateway Administration Utility discusses the use of PGAU in detail This overview explains what you must do in order to call a TIP and control a remote host transaction The gateway receives PL SQL calls from the Oracle database and issues TCP IP calls to communicate with a remote transaction program Client Application Development TCP IP Only 7 1 Overview of Client Application The following application programs make this possible 1 an I O PCB enabled remote host transaction program 2 the PGA_TCP_IMSC mapping table that has been populated using the pg4tcpmap tool with the SIDE PROFILE name as well as the TCP IP hostname port number and other IMS Connect parameters 3 a Transaction Interface Package TIP A TIP is a PL SQL package that handles communication between the client and the gateway and performs datatype conversions between COBOL and PL SQL 4 PGAU generates the TIP specification for you In the shipped samples the PGAU generated package is called pgt flip p
86. Appendix E Administration Utility Samples TIP Runtime Trace Controls Runtime trace control is the second parameter specified on a TIP initialization call It is a CHAR 8 datatype of the following form rc yourtip_init trannum wxyz0000 Table 84 describes the value of positions one to four Table 8 4 Values of Positions 1 through 4 on Second Parameter of TIP Call Item Description position 1 w controls UTL_RAW warning A value of 0 suppresses warnings a value of 1 issues warnings position 2 x controls the function entry exit tracing A value of 0 suppresses the function entry exit tracing a value of 1 enables the function entry exit tracing position 3 y controls data conversion tracing A value of 0 suppresses data conversion tracing a value of 1 enables data conversion tracing position 4 z controls gateway exchange tracing A value of 0 suppresses gateway exchange tracing a value of 1 enables gateway exchange tracing Positions 5 through 8 are reserved and ignored Generating Runtime Data Conversion Trace and Warning Support Use PGAU to regenerate the TIP and specify the GENERATE parameter DIAGNOSE PKGEX DC This includes runtime PL SQL code in the TIP which tests for and displays warnings of correct but possibly unexpected NUMBER_TO_RAW and RAW_TO_NUMBER conversions Refer to Section GENERATE on page 2 15 in Chapter 2 Procedural Gateway
87. C X 5 05 DEPT PIC X 45 05 OFFICE ADDRESS 10 STREET PIC X 20 10 CITY PIC X 15 10 STATE PIC XX 10 ZIP 15 FIRST FIVE PIC X 5 15 LAST FOUR PIC X 4 D 10 Oracle Database Gateway for APPC User s Guide Conversion Pa 05 JOBTITLE PIC X 20 PGAU alters the name of the PL SQL nested record type for each declaration in which the subfields differ in name datatype or second declaration ZIP_Typ02 and its TYPE EMPNAME Typ is RECORD FIRST_NAME CHAR 10 LAST_NAME CHAR 15 TYPE ZIP_Typ is RECORD LEFTMOST_FOUR CHAR 4 RIGHTMOST_FIVE CHAR 5 TYPE HOME_ADDRESS_Typ is RECORD STREET CHAR 20 CITY CHAR 15 STATE CHAR 2 ZIP ZIP_Typ TYPE ZIP_Typ02 is RECORD FIRST_FIVE CHAR 5 LAST_FOUR CHAR 4 TYPE OFFICE_ADDRESS_Typ is RECORD STREET CHAR 20 CITY CHAR 15 STATE CHAR 2 ZIP ZIP_Typ02 TYPE EMPREC_Typ is RECORD HIREDATE CHAR 8 BIRTHDATE CHAR 8 SKILL SKILL_Tbl EMPNO NUMBER 4 0 EMPNAME EMPNAME_Typ HOME_ADDRESS HOME_ADDRESS_ DEPT CHAR 45 OFFICE_ADDRESS OFFICE_ADDRES JOBTITLE CHAR 20 options Note the 02 appended to the reference in OFFICE_ADDRESS Typ S_Typ And the fully qualified reference to the PL SQL variable which corresponds to a HOME _ADDRESS ZIP is tipname EMPREC_Typ HOME_ADDRESS ZIP tipname EMPREC_Typ HOME_ADDRESS ZIP a OFFICE ADDRESS ZIP is T tipname
88. C interface can be used if it is preferred A sample DB2 update transaction written in COBOL using the EXEC CICS interface is provided with the gateway Any language supported by CICS Transaction Server for z OS can be used for writing commit confirm transactions With IMS TM the CPI C interface must be used making the IMS transaction an explicit APPC transaction as referred to in the IBM IMSCICS Transaction Server for z OS manuals This is necessary because it is the only way that the LU6 2 SYNCLEVEL 1 control flows are accessible to the IMS transaction When using implied APPC where GU from the IOPCB and ISRT to the IOPCB are used for receiving and sending data there is no way for the IMS transaction to access the LU6 2 SYNCLEVEL 1 control flow making it impossible to use this method for commit confirm A sample DLI database update transaction written in COBOL using the CPI C APPC interface is provided with the gateway Any language supported by IMS and CPI C can be used for writing commit confirm transactions Components Required to Support Commit Confirm The following components are required to support commit confirm a Oracle Database Gateway for APPC Server The gateway server supports commit confirm when PGA_CAPABILITY COMMIT_CONFIRM is specified in the gateway initialization file When the gateway server is running with commit confirm enabled it will connect to a local Oracle database where it maintains a
89. E override_Typ IS RECORD tranname VARCHAR2 2000 Transaction Program transync BINARY_INTEGER RESERVED E trannls VARCHAR2 50 RESERVED kf oltpname VARCHAR2 2000 Logical Unit e oltpmode VARCHAR2 2000 LOG Mode Entry netaddr VARCHAR2 2000 Side Profile tracetag VARCHAR2 2000 gateway trace idtag 7 10 Oracle Database Gateway for APPC User s Guide Calling the TIP from the Client Application FUNCTION pgtflip_init init standard tranuse IN OUT BINARY_INTEGER RETURN INTEGER FUNCTION pgtflip_init init override tranuse IN OUT BINARY_INTEGER override IN override_Typ RETURN INTEGER FUNCTION pgtflip_init init diagnostic tranuse IN OUT BNARY_INTEGER tipdiag IN CHAR RETURN INTEGER FUNCTION pgtflip_init init over diag tranuse IN OUT BINARY_INTEGER override IN override_Typ tipdiag IN CHAR RETURN INTEGER Transaction Instance Parameter This transaction instance number shown in examples as tranuse must be passed to subsequent TIP exchange and terminate functions It identifies to the gateway on which TCP IP conversation and therefore which iteration of a remote transaction program the data is to be transmitted or communication terminated A single client application might control multiple instances of the same remote transaction program or multiple different remote transaction programs all concurrently The transaction instance number
90. EMPREC_Typ OFFICE_ADDRESS Z tipname EMPREC_Typ OFFICE_ADDRESS Z T Note that the nested record type name 21 LEFTMOST_FOUR RIGHTMOST_FIVE IP FIRST_FIVE IP LAST_FOUR P_Typ02 is not used in the reference but is implicit within PL SQL s association of the nested records Datatype Conversions D 11 Conversion D 12 Oracle Database Gateway for APPC User s Guide E Tip Internals 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 If your gateway is using the SNA communication protocol This appendix refers to a sample called pgadb2i The source for this TIP is in file pgadb2i sql in the 3ORACLE_HOME dg4appc demo CICs directory for Microsoft Windows and SORACLE_HOME dg4appc demo CICS directory for UNIX based systems If your gateway is using the TCP IP communication protocol This appendix refers to a sample called pgaims The source for this TIP is in file pgtflipd sql in the 3ORACLE_HOME dg4appc demo IMS directory for Microsoft Windows and SORACLE_HOME dg4appc demo IMS directory on UNIX based systems This appendix contains the following sections Background Reading on page E 1 PL SQL Package and TIP File Separation on page E 2 Background Reading Several topics are imp
91. FORMAT Parameter Description maskopts null allowed no default value envrnmnt null allowed no default value compopts null allowed no default value The UTL_PG Interface C 7 UTL_PG Functions Return Value A RAW 2048 format conversion specification for NUMBER_TO_RAW Error and Warning Messages If you receive an ORA xxxx error or warning message refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it RAW_TO_NUMBER_FORMAT RAW_TO_NUMBER_FORMAT converts according to the RAW_TO_NUMBER conversion format r2nfmt a RAW byte string rawval in the remote host internal format into an Oracle number Syntax function RAW_TO_NUMBER_FORMAT rawval IN RAW r2nfmt IN RAW RETURN NUMBER where Table C 11 describes the parameters in this function Table C 11 RAW_TO_NUMBER_FORMAT Function Parameters Parameter Description rawval is the remote host data to be converted r2nfmt isa RAW 2048 format specification returned from MAKE_RAW_TO_NUMBER_FORMAT Defaults None Return Value An Oracle number corresponding in value to r Error and Warning Messages If you receive an ORA xxxx error or warning message refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it NUMBER_TO_RAW_FORMAT NUMBER_TO_RAW_FORMAT converts according to the NUMBER_TO_RAW conversion format n2r fmt an Oracle numb
92. Gateway for APPC Installation and Configuration Guide for Microsoft Windows Steps to Communication Between the Gateway and IMS Using TCP IP The following steps describe the communications process as illustrated in Figure 1 4 when your communication protocol is TCP IP 1 From SQL Plus execute pgaims sql This invokes the PL SQL stored procedure in the Oracle database For Microsoft Windows C gt sqlplus lt userid gt lt password gt lt database_specification_string gt SQL gt execute pgaims snoitalutargnoC For UNIX based systems sqlplus lt userid gt lt password gt lt database_specification_string gt SQL gt execute pgaims snoitalutargnoC Introduction to Oracle Database Gateway for APPC 1 15 Overview of a Gateway Using TCP IP The pgaims sql stored procedure will start up the gateway 2 The gateway which has the APPC information will call the mapping table PGA_TCP_IMSC The mapping table will map the information so that it will have the host name TCP IP address and the port number Note Rather than insert delete or update the PGA_TCP_IMSC mapping table manually you should use the pg4tcpmap tool to do so You may use the SELECT statement to query the rows 3 When the gateway has the port number and host name it will initiate communication with IMS Connect through TCP IP and it will call FLIP through IMS 4 FLIP processes the input generates the output and
93. ICS transaction called DB21 DEFINE TRANSACTION DB2I CALL DB2IMAIN DB2IDIAG SIDEPROFILE CICSPROD TPNAME DB21 LOGMODE ORAPLU62 SYNCLEVEL 0 NLS_LANGUAGE AMERICAN_AMERICA WE8EBCDIC37C Calling the TIP from the Client Application Once a TIP is created a client application must be written to interface with the TIP A client application that calls the TIP functions must include five logical sections a declaring TIP variables initializing the conversation a exchanging data terminating the conversation a error handling Declaring TIP Variables The user declarations section of the tipname doc file documents the required declarations When passing PL SQL parameters on calls to TIP functions the client application must use the exact same PL SQL datatypes for TIP function arguments as are defined by the TIP in its specification section Assume for example the following is in the TIP specification or tipname doc FUNCTION tip call1 tranuse IN BINARY_INTEGER tip_varl lo_mode pls _typel tip record io_mode tran_rectype RETURN INTEGER 4 14 Oracle Database Gateway for APPC User s Guide Calling the TIP from the Client Application TYPE tran_rectype is RECORD rec_field1 pls _typel rec_fieldN pls_typeN Table 4 2 provides a description of the function declarations Table 4 2 Function Declarations Item Description tip_call1 The TIP function name as defined in the p
94. INE CALL statements must be issued each specifying its unique public function name t ip_cal1x and the data parameter list to be exchanged Once a data item is defined using DEFINE DATA it can be referenced in multiple calls in any mode IN OUT or IN OUT For example parm5 could be used a second time in place of parm6 This implies the same data is being exchanged in both instances received into the TIP and application on tip_cal1l2 and returned possibly updated to the remote host in tip_ca114 Notice also that the remote transaction program s first five written fields are read by two separate TIP function calls tip_ca111 and tip_ca112 This could also have been equivalently accomplished with five TIP function calls of one OUT parameter 4 12 Oracle Database Gateway for APPC User s Guide Ensuring TIP and Remote Transaction Program Correspondence each or a single TIP function call with five OUT parameters Then the remote transaction program s first read field fie1d6 and subsequent written field ie147 correspond to a single TIP function call tip_cal13 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 have to correspond to different PL SQL parameters
95. IP then proceed to Section Overview of a Gateway Using TCP IP on page 1 14 Overview of a Gateway Using SNA If you are using the SNA communication protocol read the following sections to develop an understanding of how the gateway communicates with the Oracle database and with the mainframe as well as transaction types unique to your gateway and writing TIPs Transaction Types for a Gateway Using SNA The Oracle Database Gateway for APPC supports three types of transactions that read data from and write data to remote host systems one shot In a one shot transaction the application starts the connection exchanges data and terminates the connection all in a single call persistent Ina persistent transaction multiple calls to exchange data with the remote transaction can be executed before terminating the conversation multi conversational In a multi conversational transaction the database gateway server can be used to exchange multiple records in one call to the remote transaction program Refer to Remote Host Transaction Types in Chapter 4 Client Application Development SNA Only of this guide for more information about transaction types The following list demonstrates examples of the power of the Oracle Database Gateway for APPC You can initiate a CICS transaction on the mainframe to retrieve data from a VSAM file for a PC application You can modify and monitor the operation of a remote
96. It has no comparable SNA meaning You need to run the pg4tcpmap tool to map this name to the hostname port number subsystem ID and any other desired attribute of IMS Connect This name represents a group of IMS transactions with similar IMS Connect attributes You can re use the same name as long as they share the same IMS Connect attributes such as subsystem ID TIME delay or socket type Refer to Chapter 6 PG4TCPMAP Commands TCP IP Only for details This parameter is optional on a gateway using SNA Overrides the LUNAME within the Side Information Profile if the Side Information Profile was specified It specifies the SNA Logical Unit name of the transaction manager OLTP This is either the fully qualified LU name 3 to 17 characters in length or an LU alias 1 to 8 characters in length when the SNA software on your gateway system supports LU aliases Name values can be alphanumeric with and characters and a single period to delimit the network from the LU as in netname luname if fully qualified Quoted values can contain any character and delimited by quotes or apostrophes Case is preserved for all values This parameter is not applicable when using the TCP IP communication protocol This parameter is optional on a gateway using SNA Overrides the TPNAME within the Side Profile if the Side profile was specified It specifies the partner Transaction Program name to be invok
97. L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows and to Appendix B Gateway RPC Interface in this guide for more information RTP Remote Transaction Program A remote transaction program is a customer written transaction running under the control of an OLTP which the user invokes remotely using a PL SQL procedure To execute a remote transaction program through the gateway you must use RPC to execute a PL SQL program to call the gateway functions TIP Transaction Interface Package A TIP is an Oracle PL SQL package that exists between your application and the remote transaction program The transaction interface package or TIP is a set of PL SQL stored procedures that invoke the RTP through the gateway TIPs perform the Introduction to Oracle Database Gateway for APPC 1 5 Examples and Sample Files for the Gateway conversion and reformatting of remote host data using PL SQL and UTL_RAW UTL_ PG functions Figure 1 1 illustrates where the terminology discussed in the preceding sections applies to the gateway s architecture Figure 1 1 Relationship of Gateway and Oracle Database Oracle Database Operating System Transaction Oracle Net Gateway Remote Interface Packag
98. LTP host name IMS Connect port number and IMS destination ID PGA Procedural Gateway Administration PGA is a general reference within this guide to all or most components comprising the Oracle Database Gateway for APPC This term is used when references to a specific product or component are too narrow PGDL Procedural Gateway Definition Language PGDL is the collection of statements used to define transactions and data to the PGAU PL SQL Stored Procedure Specification PL SQL package This is a precompiled PL SQL procedure that is stored in Oracle database UTL_RAW PL SQL Package the UTL_RAW Functions This component of the gateway represents a series of data conversion functions for PL SQL RAW variables and remote host data The types of conversions performed depend on the language of the remote host data Refer to Appendix D Datatype Conversions in this guide for more information 1 4 Oracle Database Gateway for APPC User s Guide Terms UTL_PG PL SQL Package the UTL_PG Functions This component of the gateway represents a series of COBOL numeric data conversion functions Refer to NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values in Appendix C of this guide for supported numeric datatype conversions Oracle Database This is any Oracle database instance that communicates with the gateway for purposes of performing RPCs to execute RTP The Oracle database can be on the same system as the gateway or on a different sy
99. No transaction attributes will change This allows any new TIP to perform the same initialization or termination with the same RHT as the former large TIP The old DEFINE TRANSACTION statement of the former large TIP should now exclude any call definitions which are being moved to new small TIPs APPC Conversation Sharing Example Assume the existence of RHTs A B and C and that RHT A performs a menu selection and calls RHT B for a query function or RHT C for an update followed by a select function You could define the following DATA and CALLs DEFINE DATA choice DEFINE DATA input m DEFINE DATA answer a DEFINE DATA record Client Application Development SNA Only 4 23 APPC Conversation Sharing a DEFINE CA menu_A callname pick parms choice in a DEFINE CA query_B callname query parms input in answer out a DEFINE CA update_C callname update parms record in DEFINE CALL select_C callname select parms record out The following example TIPs could be defined Example 1 This example does not use APPC conversation sharing but is a valid TIP definition created before release 3 4 0 combining the functions of RHTs A Band C DEFINE TRANSACTION rhtABC calls menu_A query_B update_C select_C tpname RHTA This TIP includes all data definitions and calls and might b
100. OM 9900 IMSE 1 Example for UNIX based systems sqlplus userid password databasename SQL gt column hostname format A22 SQL gt column portnumber format A6 SQL gt select sideprofilename hostname portnumber imsdestid commitmode from pga_tcp_imsc SIDEPROF HOSTNAME PORTNU IMSDESTI IMSPGA MVS08 US ORACLE COM 9900 IMSE 1 PG4TCPMAP Commands TCP IP Only 6 7 pg4tcpmap Tool Commands 6 8 Oracle Database Gateway for APPC User s Guide T Client Application Development TCP IP Only This chapter discusses how you will call a TIP and control a remote host transaction if your gateway uses TCP IP support for IMS Connect It also provides you with the steps for preparing and executing a gateway transaction This chapter assumes a aremote host transaction RHT has already been written a a TIP corresponding to the RHT has already been defined using the steps described in Chapter 3 Creating a TIP the PGA_TCP_IMSC mapping table has been populated using the pg4tcpmap tool with the SIDE PROFILE name TCP IP hostname port number and other IMS Connect parameters This chapter contains the following sections Overview of Client Application on page 7 1 Preparing the Client Application on page 7 3 a Ensuring TIP and Remote Transaction Program Correspondence on page 7 4 Calling the TIP from the Client Application on page 7 8 Exchanging Data on page 7 13 a Calling PG4TCPM
101. ONFIRM request in the form of a status from the last APPC RECEIVE The OLTP application issues a COMMIT using an appropriate OLTP function The OLTP commits all database updates made by the application since the last COMMIT including the commit confirm transaction log update Once the database updates have been committed the OLTP returns control to the application with a return code indicating the status of the COMMIT T The OLTP application sends an APPC CONFIRMED to the gateway The gateway receives the CONFIRMED and returns COMMIT OK to the Oracle database The Oracle database sends COMMIT to each participant in the distributed transaction other than the gateway Each participant commits its database updates and responds COMMIT OK to the Oracle database The Oracle database sends a FORGET to the gateway The gateway receives the FORGET and starts a new APPC conversation with the FORGET RECOVERY transaction at the OLTP sends it a FORGET request and an APPC CONFIRM The FORGET RECOVERY transaction receives the FORGET request and deletes the entry from the commit confirm transaction log for the current Oracle transaction and commits the delete The FORGET RECOVERY transaction sends an APPC CONFIRMED to the gateway to indicate that the FORGET was processed and then terminates The gateway receives the CONFIRMED and deletes the pending transaction row from the PGA_CC_
102. Oracle Database Gateway for APPC User s Guide 11g Release 2 11 2 E12071 02 September 2009 ORACLE Oracle Database Gateway for APPC User s Guide 11g Release 2 11 2 E12071 02 Copyright O 1996 2009 Oracle and or its affiliates All rights reserved Primary Author Maitreyee Chaliha Contributor Vira Goorah Govind Lakkoju Peter Wong Juan Pablo Ahues Vasquez Peter Castro and Charles Benet This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws Except as expressly permitted in your license agreement or allowed by law you may not use copy reproduce translate broadcast modify license transmit distribute exhibit perform publish or display any part in any form or by any means Reverse engineering disassembly or decompilation of this software unless required by law for interoperability is prohibited The information contained herein is subject to change without notice and is not warranted to be error free If you find any errors please report them to us in writing If this software or related documentation is delivered to the U S Government or anyone licensing it on behalf of the U S Government the following notice is applicable U S GOVERNMENT RIGHTS Programs software databases and related documentation and technical data delivered to U S Government customers are commercial computer so
103. Oracle Oracle Net L _ oracle Net Database Gateway APPC Other Options aS CCICS 400 CICS VSE TCP IP a Po TCPAP IMS CONNECT IMS TM Client Communication with the Gateway All the communication between the user or client program and the gateway is handled through a TIP which executes on an Oracle database The TIP is a standard PL SQL package that provides the following functions a declares the PL SQL variables that can be exchanged with a remote transaction program a calls the gateway packages that handle the communications for starting the conversation exchanging data and terminating the conversation a handles all datatype conversions between PL SQL datatypes and the target program datatypes The PGAU provided with the gateway automatically generates the TIP specification The gateway is identified to the Oracle database using a database link The database link is the same construct used to identify other Oracle databases The functions in the gateway are referenced in PL SQL as function_name dblink_name RPC Functions The Oracle Database Gateway for APPC provides a set of functions that are called by the client through RPC These functions direct the gateway to initiate transfer data with and terminate RTP running under an OLTP on another system Table 1 1 lists the RPC functions and the correlating commands that are invoke
104. PENDING table The gateway returns FORGET OK to the Oracle database The Oracle database returns control to the Oracle application Figure 5 1 Commit Confirm Flow with Synclevel 1 illustrates the Commit Confirm logic flow described in the previous section 5 6 Oracle Database Gateway for APPC User s Guide Commit Confirm Flow Figure 5 1 Commit Confirm Flow with Synclevel 1 Oracle Application Database Gateway OLTP OLTP App commit gt 2 RECEIVE PREPARE a4 S 4 COMMIT gt 5 gt CONFIRM 6 COMMIT 7 return code 9 3 CONFIRMED lt _ Commit 10 OK Program COMMIT PB Continues i 11 1 Forget Recover FORGET 12 gt Transaction FORGET 13 DELETE LOG ENTRY ig 16 lt 15 lt 14 Program FORGET FORGET Continues COMMIT OK OK Gateway Server Commit Confirm Transaction Log The commit confirm transaction log consists of a single table PGA_CC_PENDING This table contains a row for each in flight Oracle transaction that includes the commit confirm gateway The table is maintained by the gateway server and is similar in function to the Oracle database s DBA_2PC_PENDING table Note that a row is not inserted into this table until a COMMIT is received by the gateway and the row is deleted when a FORGET is received by the gateway There is no involvement by the gatew
105. PKGEX DC Or you can recompile the previous version of the TIP body if it was saved Methods A and B allow you to use the same TIP without alteration but without tracing or warnings These methods are reversible without alteration or replacement of the TIP Tracing and warnings can be redisplayed should a problem recur Method C also suppresses data conversion tracing and warnings and incurs reduced overhead by avoiding tests but is not reversible without regenerating the TIP or recompiling an alternate version with data conversion tracing and warning diagnostics imbedded The logic for function entry exit and gateway exchange tracing is included in every TIP and cannot be removed It can be disabled by method A or B Problem Analysis of Data Conversion and Truncation Errors Oracle Database Gateway for APPC data lengths are limited by PL SQL to 32 763 bytes per APPC exchange and PL SQL variable The following steps can be used to diagnose data conversion or truncation errors Refer to Chapter 3 Creating a TIP to review the proper values and definitions referenced in items 1 through 4 below 1 Ensure that the COBOL definitions used in the RHT match the input to PGAU 2 Ensure the RHT transmission buffers are of sufficient length 3 If your gateway uses SNA Ensure the RHT APPC call addresses the correct transmission buffer and uses the correct data length If your gateway uses TCP IP Ensure the RHT I O PCB call addresses the
106. Ps that share a conversation and passing the tranuse value returned to the other TIP functions as each is called in its desired order Any TIP init function can be used provided that all TIPs were defined with the same DEFINE TRANSACTION TPNAME or SIDEPROFILE value The TPNAME or SIDEPROFILE value specifies which RHT to initialize When the init function of an APPC conversation sharing capable TIP is called to initialize a conversation the tranuse value returned indicates conversation sharing is enabled By passing that same tranuse value when calling functions in other TIPs those other TIPs perform their transfers on the same conversation already initialized provided that all TIPs involved were generated at Version 3 4 0 or later APPC Conversation Sharing TIP Compatibility TIPs generated at 3 4 0 or later of the database gateway use and expect different values for tranuse than do pre 3 4 0 TIPs If a pre 3 4 0 TIP is used to initialize a conversation and its tranuse value is passed to a 3 4 0 or later generated TIP the following exception is raised ORA 20704 PGA_TIP tranuse value cannot be shared Pre 3 4 0 generated TIPs do not detect the different tranuse value for shared conversations however and this can result in unpredictable errors Caution All TIPs called in a shared conversation must have been generated at 3 4 0 or later No TIPs generated before 3 4 0 can par
107. RATE on page 2 15 in Chapter 2 Procedural Gateway Administration Utility Note that the output of the trace is different for a gateway using SNA than for a gateway using TCP IP However the method of invoking the trace is the same regardless of which communication protocol you are using On Microsoft Windows the gateway server tracing must also be enabled in SORACLE_HOME dg4appc admin initsidora Set the parameters SET TRACE _LEVEL 255 and SET LOG_DESTINATION C oracle pga 11 2 dg4appc log On UNIXbased systems the gateway server tracing mustalso be enabledin SORACLE_HOME dg4appc admin initsid ora Set the parameters SET TRACE_LEVEL 255 and SET LOG_DESTINATION oracle pga 11 2 dg4appc log Refer to Gateway Server Tracing on page 8 10 in this guide for more information about tracing a If your gateway is using SNA Refer to Appendix A Gateway Initialization Parameters for SNA Protocol in your Oracle Database Gateway for APPC Installation and Configuration Guide for more information about these parameters If your gateway is using TCP IP Refer to Appendix B Gateway Initialization Parameters for TCP IP Communication Protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Install
108. S D 8 USAGE PASS D 2 USAGE SKIP D 8 DEFINE PGAU call list 3 3 DEFINE TRANSACTION 1 13 2 2 2 10 3 5 4 23 on gateway using TCP IP 1 18 sample F 2 DEFINE TRANSACTION parameters 2 10 3 3 defining correlation between TIP and RTP 2 2 DESCRIBE 2 13 DESCRIBE parameters 2 13 DISCONNECT 2 13 DISCONNECT parameters 2 13 EXECUTE 2 14 EXECUTE parameters 2 14 EXIT 2 14 EXIT parameters 2 14 formatting of Call and Transaction reports 2 25 four main types in control file 1 12 1 17 GENERATE 2 15 3 5 3 7 3 8 4 10 7 4 E 2 error messages 8 3 on gateway using SNA 1 13 on gateway using TCP IP 1 18 parameters 2 15 problem analysis 8 2 sample F 2 Index 6 support and non support for parameters over 32K length D 2 traces 8 1 GROUP 2 18 3 7 HOST 2 19 parameters 2 19 on gateway using SNA 1 13 PRINT 2 20 REDEFINE DATA 2 20 A 11 sample F 6 REM 2 23 REM parameters 2 23 REPORT 2 24 REPORT parameters 2 24 SET 2 26 SET parameters 2 26 SHOW 2 27 SHOW parameters 2 27 SPOOL 2 28 SPOOL parameters 2 29 TRANSACTION 2 25 UNDEFINE CALL 2 29 UNDEFINE CALL parameters 2 29 UNDEFINE DATA 2 30 UNDEFINE DATA parameters 2 30 UNDEFINE TRANSACTION 2 30 UNDEFINE TRANSACTION parameters 2 30 UNDEFINE sample F 7 VARIABLE 2 31 VARIABLE parameters 2 31 PGAU script file adding spool and echo 3 7 creating 3 5 pgau tre file 2 16 2 18 PGAXFER 7 7 B 4 PGAXFER function 1 4 1 9
109. SYNCLEVEL 0 NLS_LANGUAGE AMERICAN_AMERICA WE8EBCDIC37C GENERATE DB21I PKGNAME PGADB21 OUTFILE pgadb2i GROUP Usage Notes a Nonon PGAU commands such as ORACLE or SQL can be placed inside the parentheses delimiting the group APGAU script can contain multiple GROUPs Each GROUP can be interspersed with SOL commands such as COMMIT or SELECT or with PGAU commands such as GENERATE or REPORT a The first failing PGAU statement within the group causes a savepoint ROLLBACK to conditions at the beginning of the group All subsequent commands within the group are flushed and not examined PGAU execution resumes with the statement following the group If that statement is a COMMIT all PG DD changes made before the failing group are committed m You must place at the end of the command Purpose Use this command to execute an operating system command without exiting PGAU Syntax The HOST command has the syntax HOST host_command Parameters host_command is any valid operating system command Examples HOST vi log out HOST ls la HOST pwd HOST Usage Notes Using the HOST command starts a new command shell under which to execute the specified operating system command This means that any environment changes caused by the executed command affect only the new command shell started by PGAU and not the command shell under which PGAU itself is executing For example a cd command
110. TE PIC X 10 10 SALARY PIC S9999999V99 USAGE COMP 3 10 BONUS PIC S9999999V99 USAGE COMP 3 10 COMM PIC S9999999V99 USAGE COMP 3 10 YTD 15 SAL PIC S9 9 V99 USAGE COMP 3 15 BON PIC S9 9 V99 USAGE COMP 3 15 COM PIC S9 9 V99 USAGE COMP 3 Administration Utility Samples F 3 Sample Implicit Versioning Definitions To determine which DATA version number was assigned this SOL query can be issued SELECT MAX pd version FROM pga_data pd WHERE pd dname EMPREC To determine additional information related to the updated version of EMPREC this query can be used SELECT FROM pga_data pd WHERE pd dname EMPREC This example creates a new CALL version of DB2 IMAIN because the DB21IMAIN CALL was defined previously DEFINE CALL DB2IMAIN PKGCALL PGADB2I_MAIN PARMS EMPNO IN EMPREC OUT VERSION ddddd where ddddd is the version number of the EMPREC DATA definition queried after the previous DEFINE DATA updated EMPREC To determine which call version number was assigned this SOL query can be issued SELECT MAX pc version FROM pga_call pc WHERE pc cname DB2IMAIN To determine additional information related to the updated version of DB2IMAIN this query can be used SELECT FROM pga_call pc WHERE pc cname DB2IMAIN The DEFINE TRANSACTION example creates a new TRANSACTION versio
111. TIP Runtime Gateway Exchange Tracing on page 8 7 for more information Make the following changes to the PL SQL application that calls the Transaction Interface Package s to execute remote transaction s 1 Adda call to PGATCTL before any calls to TIP initialization functions are made PGATCTL dblink convid traceF traces Where Table 8 5 describes the parameters in PGATCTL Table 8 5 PGATCTL Parameters Parameter Description dblink is the name of the database link to the gateway convid 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 traceF is the trace control function to be performed traces specifies which traces are to be enabled as described previously in the discussion of the SET TRACE_LEVEL initialization parameter This call sets the trace flags for all new conversations started after the call to the value specified by traces 2 Recompile the PL SQL application to pick up the new trace call 8 12 Oracle Database Gateway for APPC User s Guide A Database Gateway for APPC Data Dictionary This appendix contains the following sections PG DD Environment Dictionary on page A 1 PG DD Active Dictionary on page A 5 The Procedural Gateway Data Dictionary PG DD is maintained
112. TIP Runtime Data Conversion Tracing To enable data conversion tracing in yourtip the client application should call the TIP initialization function with the following statement rc yourtip_init trannum 00100000 The following is input to the TIP trace pipe inlet at initialization time data conversion trace enabled Controlling TIP Runtime Gateway Exchange Tracing To enable runtime gateway exchange tracing in yourtip the client application should call the TIP initialization function with the following statement rc yourtip_init trannum 00010000 The following is input to the TIP trace pipe inlet at initialization time gateway exchange trace enabled Suppressing TIP Warnings and Tracing After debugging is finished there are two ways to suppress the following data conversion tracing Conversion warnings a function entry exit tracing gateway exchange tracing You can 1 Call the TIP initialization function without passing any diagnostic control parameters rc yourtip_init trannum 2 Call the TIP initialization function passing a revised diagnostic control parameter which disables all tracing and warnings rc yourtip_init trannum 00000000 Troubleshooting 8 7 Problem Analysis of Data Conversion and Truncation Errors A third method described in Method C removes the logic for data conversion tracing Conversi n warnings 3 Generate the TIP again without
113. The PGAU DEFINE CALL statement specifies how the generated TIP is to be called by the client application and which data parameters are to be exchanged with the remote host transaction for that call Each PGAU DEFINE CALL statement might specify the name of the TIP function one or more data parameters and the IN OUT mode of each data parameter Data parameters must have been previously defined with PGAU DEFINE DATA statements Refer to DEFINE CALL on page 2 2 in Chapter 2 Procedural Gateway Administration Utility and Sample PGAU DEFINE CALL Statements in Appendix F Administration Utility Samples for more information Client Application Development SNA Only 4 11 Ensuring TIP and Remote Transaction Program Correspondence PGAU DEFINE CALL processing stores the specified information in the PG DD for later use by PGAU GENERATE PGAU GENERATE then creates the following in the TIP package specification a declarations of public PL SQL functions for each CALL defined with PL SQL parameters for each DATA definition specified on the CALL a declarations of the public PL SQL data parameters The client application calls the TIP public function as a PL SQL function call using the function name and parameter list specified in the PGAU DEFINE CALL statement The client application might also declare by reference private variables of the same datatype as the TIP public data parameters to facilitate data
114. This is treated as documentation The remote host transaction data is converted as a PL SQL CHAR datatype according to character datatype as discussed in PIC X Datatype Conversions on page D 2 for both IN and OUT parameters Datatype Conversions D 5 Conversion Table D 4 Cont Format Conversion Descriptions Item Description LENGTH IS field 2 OCCURS n TIMES This is an Oracle extension to the data definition as stored in the PG DD This extension exists only in the PGAU context and is not valid COBOL syntax The purpose of this extension is to provide a means for variable length character data to be processed more efficiently by the TIP conversion logic This is an alternative to defining a variable length PIC X field as PIC X 1 OCCURS DEPENDING ON field 2 where field 2 is the length of the field With this extension the same field could be defined as PIC X 5000 LENGTH IS field 2 where field 2isthe length of the field The TIP is able to pick up the length and do the character set conversion on the field with a single UTL_ RAW CONVERT call instead of using a loop to do the conversion one character at a time Note that the use of this construct does not affect the COBOL program The PIC X or PIC G field is still fixed length as far as COBOL is concerned so the position of the data does not change nor does the amount of data that is transferred between the gateway and the OLTP However if the field i
115. _call4 parm8 IN gt TCP IP RECEIVE field8 into remote TP parm9 IN gt TCP IP RECEIVE field9 into remote TP parm10 IN gt TCP IP RECEIVE field10 into remote TP 7 6 Oracle Database Gateway for APPC User s Guide Ensuring TIP and Remote Transaction Program Correspondence To define these four public functions to the TIP four PGAU DEFINE CALL statements must be issued each specifying its unique public function name tip_cal1x and the data parameter list to be exchanged Once a data item is defined using DEFINE DATA it can be referenced in multiple calls in any mode IN OUT or IN OUT For example parm5 could be used a second time in place of parm6 This implies the same data is being exchanged in both instances received into the TIP and application on tip_ call2 and returned possibly updated to the remote host in tip_cal14 Notice also that the remote transaction program s first five written fields are read by two separate TIP function calls tip_ca1l11 and tip_cal12 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 fie1d6 and subsequent written field ie1d7 correspond to a single TIP function call tip_ca113 with a single IN OUT parameter parm6 This use of a single IN OUT parameter implies that the remote tr
116. _rectype is RECORD rec_field1 pls_typel rec_fieldN pls_typeN Where Table 7 2 provides a description of each of the parameters Table 7 2 Function Declarations Parameter Description tip_call1 The TIP function name as defined in the package specification tranuse The remote transaction instance parameter returned from the TIP init function identifying the conversation on which this TIP call is to exchange data tran_rectype The PL SQL record datatype declared in the tipname TIP specification This is the same value as in the TYPE tran_rectype is RECORD statement pls_typeN Is a PL SQL atomic datatype rec_fieldN Is a PL SQL record field corresponding to a remote transaction program record field In the client application PL SQL atomic datatypes should be defined as the exact same datatype of their corresponding arguments in the TIP function definition The following should be coded in the client application before the BEGIN command appl_var pls typel declare appl variable for TIP datatypes need not be redefined They must be declared locally within the client application appearing in the client application before the BEGIN appl_record tipname tran_rectype declare appl record Table 7 3 describes the meaning of each procedure declaration Table 7 3 Procedure Declarations Item Description appl_record Is a PL SQL record exchanged with the TIP and used within the client appli
117. a LOCAL_LANGUAGE REMOTE LANGUAGE LENGTH LENGTH IS variable Max length gt attr name string lengths attr number 9 0 Attribute id assigned Foreign key pga_data_values attr Set from an Oracle sequence object for each supported data attribute inserted into the PG DD coltype varchar2 4 Type of Oracle column from which attribute value is retrieved from pga_data_values For example NUM gt pga_data_values numval CHAR gt pga_data_values charval DATE gt pga_data_values dateval required char 1 If not null required keyword pga_data_values A row exists in the pga_data_values table for each attribute of each data item defined by each data definition Table A 22 presents the column type and content information for pga_data_ values Table A 22 pga_data_values Column Type Content fld number 9 0 Data Field Definition number from pga_data fld Primary key A 14 Oracle Database Gateway for APPC User s Guide PG DD Active Dictionary Table A 22 Cont pga_data_values Column Type Content attr number 9 0 Attribute id from pga_data_attr attr Primary key numval number 9 0 Attribute s numeric value For example number for LEVEL number for REMAPSWN redefines number for REPGRPFF occurs n number for REPGRPVF odo first n number for REPGRPVL odo last n If anon numeric attribute this
118. a PL SQL VARCHAR if a VARCHAR is desired Character set conversion is performed for single byte encoded remote host character data using either DEFINE TRANSACTION NLS_LANGUAGE character set for an entire transaction or REDEFINE DATA REMOTE_LANGUAGE character set for a single field if specified local Oracle character data using either LANGUAGE character set of integrating server for an entire transaction or REDEFINE DATA LOCAL_LANGUAGE character set for a single field if specified PIC G Datatype Conversions PGAU generated TIPs convert the COBOL G datatype to a PL SQL VARCHAR2 datatype of the same length allowing 2 bytes for every character position Character set conversion is performed for double byte and multi byte encoded remote host character data using either DEFINE TRANSACTION REMOTE MBCS character set for an entire transaction or REDEFINE DATA REMOTE_LANGUAGE character set for a single field if specified local Oracle character data using either DEFINE TRANSACTION LOCAL MBCS character set for an entire transaction or REDEFINE DATA LOCAL_LANGUAGE character set for a single field if specified Alphanumeric and DBCS Editing Field Positions Table D 2 illustrates how PGAU interprets COBOL symbols in datatype conversions by providing the definiti
119. a 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_L EV EL at SORACLE_HOME dg4appc admin initsid ora for Microsoft Windows or SORACLE_HOME dg4appc admin initsid ora on UNIX based systems This is a useful debugging tool when developing a new PL SQL application B 6 Oracle Database Gateway for APPC User s Guide Calling Gateway Functions to Execute Transaction Programs 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 Gateway RPC Interface B 7 Calling Gateway Functions to Execute Transaction Programs B 8 Oracle Database Gateway for APPC User s Guide C The UTL_PG Interface The Oracle Database Gateway for APPC requires the use of the RAW datatype to transfer data to and from PL SQL without any alteration by Oracle Net This is necessary because only the PL SQL applications have information about the format of the data being sent to and received from the remote transaction programs Oracle Net only has information about the systems where the PL SQL application and the gateway server are running If Oracle Net is allowed to perform translation on the data flowing betwee
120. ackage specification tranuse The remote transaction instance parameter returned from the TIP init function identifying the conversation on which this TIP call is to exchange data tran_rectype The PL SQL record datatype declared in the tipname TIP specification This is the same value as in the TYPE tran_rectype is RECORD statement pls_typeN Is a PL SQL atomic datatype rec_fieldN Is a PL SQL record field corresponding to a remote transaction program record field In the client application PL SQL atomic datatypes should be defined as the exact same datatype of their corresponding arguments in the TIP function definition The following should be coded in the client application before the BEGIN command appl_var pls typel declare appl variable for TIP datatypes need not be redefined They must be declared locally within the client application appearing in the client application before the BEGIN appl_record tipname tran_rectype declare appl record Table 4 3 describes the command line arguments Table 4 3 Command Line Arguments Item Description tip_call1 The TIP function name as defined in the package specification tranuse The remote transaction instance parameter returned from the TIP init function identifying the conversation on which this TIP call is to exchange data tran_rectype The PL SQL record datatype declared in the tipname TIP specification This is the same value as in
121. acle Database Gateway for APPC User s Guide Client Application Requirements Multi conversational remote host transaction client applications must Declare RHT TIP datatypes to be exchanged All client applications must declare variables to be exchanged with the RHTs using TIPs PL SQL datatypes for such variables have already been defined in the TIP corresponding to each RHT and the client application need only reference the TIP datatype in its declaration Refer to Declaring TIP Variables on page 4 14 for more information Also refer to the TIP content documentation file for the specific TIP RHT for more information about the exact usage of these variables Initialize each RHT involved using the TIP initializing function A specific customized TIP exists for each RHT as defined in the PG DD Client applications that control multiple RHTs are multi conversational and must start each RHT and its associated conversation This is done by calling each TIP initialization function as before but multiple TIPs are initialized If a single RHT is designed to perform multiple services for one or more callers and if the client application is designed to use this RHT the TIP corresponding to that RHT can be initialized multiple times by the client application The client application subsequently distinguishes from active RHTs under its control using TIP schema tipname callname when multiple TIP RHITs are being controlled By encoding the sam
122. ad of SQL Plus for general database administration Alternatively PGAU commands can be supplied in a control file The control file contains one or more PGAU commands for manipulating the PG DD or generating TIP specifications PGAU issues status messages on each operation The message text is provided through Globalization Support message support PGAU processes each command in sequence An error on a single command causes PGAU to skip that command To run PGAU the PG DD tables must already have been created Refer to the gateway configuration chapters corresponding to your communications protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows COMMIT ROLLBACK Processing The following sections provide information on COMMIT ROLLBACK processing COMMIT Processing PGAU never issues COMMIT commands As the user it is your responsibility to COMMIT PG DD changes when all the changes are implemented Otherwise Oracle issues a COMMIT command by default when you exit the PGAU session If PG DD changes are not to be committed you must run a ROLLBACK command before exiting ROLLBACK Processing PGAU sets a savepoint at the beginning of each PGAU command that alters the PG DD and at the
123. agcics 1 11 parameter 2 17 See TIP specifying names 4 14 7 8 PL SQL stored procedure 5 5 changing trace level B 6 starting up communication with mainframe 1 11 1 15 PL SQL stored procedure specification also called TIP See PL SQL package PRINT command 2 20 privileges needed to use TIPs 4 27 problem analysis of data conversion and truncation errors 8 8 with PG DD diagnostic references 8 2 with PG DD select scripts 8 3 with TIP runtime traces 8 5 Procedural Gateway Administration see PGA Procedural Gateway Administration Utility see PGAU 1 8 R RAW_TO_NUMBER FORMAT function C 8 RAW_TO_NUMBER function C 3 recompilation errors causes E 4 REDEFINE DATA statement A 11 F 6 REDEFINES D 7 REM command 2 23 remote host transactions RHT APPC conversation sharing 4 20 attributes needed 4 13 7 7 client application 4 7 defined using the PGAU DEFINE TRANSACTION statement 4 13 7 7 evaluating 3 2 multi conversational client applications 4 9 one shot client applications 4 7 persistent client applications 4 8 requirements understanding 4 3 steps involved in 4 6 types on gateway using SNA 1 10 4 4 on gateway using TCP IP 7 4 remote procedural call See RPC remote procedural call RPC A 9 calling the gateway B 1 executing gateway functions B 1 parameters B 6 PGAINIT and PGAINIT_SEC B 3 PGAINIT and PGAINIT_SEC parameters B 3 PGATCTL B 6 PGATERM B 5 PGATERM parameters B 5 PGATRAC B
124. age 2 6 maintenance 2 3 overview A 1 preparing client application on gateway using SNA 4 3 on gateway using TCP IP 7 3 purpose of REPORT command 2 24 relationship to PGAU 2 1 remote transaction definitions 2 3 ROLLBACK command 2 2 select scripts 8 3 storage of information needed for PGAU GENERATE to perform 4 10 7 4 transaction attributes 4 18 7 12 USAGE SKIP D 8 version definition tables 2 5 pg4tcpmap tool 1 16 3 4 7 1 calling to map DEFINE TRANSACITON parameters 7 14 commands to operate PGA_TCP_IMSC table 6 6 definition 1 4 description and function in the gateway 1 3 function 1 3 in mapping input parameters 6 1 function in remote transaction initiation 1 9 preparation for populating PGA_TCP_IMSC table 6 1 setting parameters in initsid ora 6 5 to map SideProfile name 2 11 PGA administrator 2 2 definition 1 4 pga_call table A 9 pga_call_parm table A 10 PGA_CC_PENDING table commit confirm transaction log 5 7 pga_compilers table A 3 pga_data table A 11 pga_data_attr A 13 pga_data_values table A 14 pga_datatype_attr table A 4 pga_datatype_values table A 4 pga_datatypes table A 4 pga_env_attr table A 3 pga_env_values table A 3 pga_environments table A 2 pga_fields table A 12 pga_maint table A 2 pga_modes constant A 5 PGA_TCP_IMSC table 1 16 3 4 6 1 7 1 7 2 7 8 content and parameters 6 2 querying 6 7 PGA_TCP_PASS 6 2 PGA_TCP_USER 6 2 pga_trans table A 6 pga_trans_
125. ains all functions and data for all RHTs which a client application might need to call Creating TIPs with a superset of RHTs often causes such TIPs to be too large for PL SQL to compile Conversely with APPC conversation sharing each RHT or even each RHT data exchange for those RHTs which perform multiple different data exchange operations can be defined in a single TIP which is smaller and less likely to exceed PL SQL compilation limits Client Application Development SNA Only 4 21 APPC Conversation Sharing APPC Conversation Sharing Usage APPC conversation sharing is automatically available in every TIP generated at 3 4 0 or later No TIPs generated before 3 4 0 can participate in APPC conversation sharing TIPs generated before 3 4 0 must be regenerated using PGAU 3 4 0 or later to participate in APPC conversation sharing PGAU is upward compatible and regeneration should be transparent provided only the regenerated TIP body tipname pkb is recompiled If the TIP specification is also recompiled the client application needs recompilation as well Refer to Appendix E Tip Internals for more detailed information Definition and generation of TIPs is accomplished as previously discussed in Chapters 1 2 and 3 No additional options or parameters need be specified Run time use of APPC conversation sharing is under the control of the client application It is accomplished simply by calling the init function of one of the TI
126. ameters 2 30 Oracle Database Gateway for APPC User s Guide PGAU Commands VARIABLE Table 2 12 UNDEFINE TRANSACTION Parameter Descriptions Parameter Description TRANSACTION tname Mandatory parameter It specifies the name associated with the item to be dropped If no version is specified only the latest highest numbered version is removed VERSion datavers Optional parameter It specifies which singular version of a definition is to be removed or if ALL then all definitions are removed for the given definition named The default of the transvers ALL highest numbered version of the named definition is assumed if VERSION is omitted callvers Examples Refer to Sample PGAU UNDEFINE Statements in Appendix F for examples of UNDEFINE TRANSACTION commands UNDEFINE TRANSACTION Usage Notes a Removing definitions only prevents PL SQL packages from being subsequently generated TIPs can still be recreated if the pkh and pkb specification files remain in existence Previously created TIPs can be invoked if they remain in the database of the Oracle database Whether such TIPs execute successfully depends on whether the corresponding remote transaction programs are still active A TRANSACTION definition can be removed at any time wae You must place at the end of the command Purpose Use this command to declare a bind variable for use in the current session with
127. ameters NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values This table lists the valid values for the format arguments for NUMBER_TO_RAW and RAW_TO_NUMBER and related functions Following are examples of some valid COBOL picture masks Any valid COBOL picture mask may be used Refer to the appropriate IBM COBOL programming guides for an explanation of COBOL picture masks mask COBOL picture mask lt n lt 18 lt n lt 18 lt n s lt 18 lt n s lt 18 PIC 9 n where PIC S9 n where PIC 9 n V9 s where PIC S9 n V9 s where PIC S9999999V99 PIC V99999 PIC SV9 5 PIC 999 00 PIC 99 99 99 PIC ZZZ 99 PIC PPP99 PIC 999 99 PIC 999 99 PIC 999 99 PIC 999 99 PIC 99 PIC 9999 99DB PIC 9999 99CR errre maskopts COBOL picture mask options COMP USAGE IS COMP USAGE IS COMPUTATIONAL COMP 3 USAGE IS COMP 3 USAGE IS COMPUTATIONAL 3 COMP 4 USAGE IS COMP 4 USAGE IS COMPUTATIONAL 4 DISPLAY The UTL_PG Interface C 11 NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values USAGE IS DISPLAY SIGN SIGN SIGN SIGN SIGN SIGN Is IS IS IS IS IS envenmnt LEAD LEAD LEAD TRAI TRAI TRAI COBO LING ING ING SEPARATE ING SEPARATE CHARACTER ING SEPARATE ING SEPARATE CHARACTER L environment clause CURRENCY SIGN IS x where x is a valid currency sign character DECIMAL POINT IS COMMA compname COBO IBMVSCOBOLII
128. ameters TRACE_LEVEL 255 LOG_DESTINATION lt valid directory gt Refer to Chapter 8 Troubleshooting for information about tracing 4 Make certain that the PGA_TCP_IMSC table has been created Issue SORACLE_HOME dg4appc admin pgaimsc sql on Microsoft Windows Or SORACLE_HOME dg4appc admin pgaimsc sql on UNIX based systems Figure 6 1 illustrates the relationship between the gateway the database and the pg4tcpmap tool in mapping the Side Profile Name to TCP IP and IMS Connect attributes in the PGA_TCP_IMSC table Figure 6 1 Mapping SNA Parameters to TCP IP Using the pg4tcpmap Tool Operating System Database PGA_TCP_IMSC Table Oracle Net Operating System Gateway C gt pg4tcpmap Side Profile name is PGAIMST remote host name is MVS08 IMS Connect port number is 9900 conversational protocol is Timer is D socket connection type is T PG4TCPMAP Commands TCP IP Only 6 5 pg4tcpmap Tool Commands TCP IPTCP IP EEA EH EEE EE EE EE EE EE EEE EEE EE HE EE EE RR RA EEE EEE EH EE EE EEE EE A copy of the screen output file for the pg4tcpmap tool is located in Appendix B Gateway Initialization Parameters for TCP IP Communication Protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 6
129. ameters supplied by the receiving remote host transaction all buffering into the format expected by the receiving remote host transaction 7 4 Oracle Database Gateway for APPC User s Guide Ensuring TIP and Remote Transaction Program Correspondence a all data unbuffering from the format supplied by the sending remote host transaction all data conversion to PL SQL OUT parameters supplied by the sending remote host transaction PGAU determines the information needed to generate the conversion and buffering logic from the data definitions included in the remote host transaction program PGAU DEFINE DATA reads this information from files such as COBOL copy books or in stream from scripts and saves it in the PG DD for repeated use The Gateway Administrator needs to transfer these definition files from the remote host to the Oracle host where PGAU runs From the data definitions stored in the PG DD PGAU GENERATE determines the remote host datatype and matches it to an appropriate PL SQL datatype It also determines data lengths and offsets within records and buffers and generates the needed PL SQL logic into the TIP Refer to the PGAU DEFINE DATA statement on page 2 8 in Chapter 2 Procedural Gateway Administration Utility and Sample PGAU DEFINE DATA Statements in Appendix F Administration Utility Samples for more information All data that are referenced as parameters by subsequent calls must first be define
130. and hence CHAR datatypes are used in TIPs for PIC X data fields However even when the PIC X field contains DBCS or MBCS data a CHAR variable is still used and padded with blanks if needed Some remote host applications bracket a PIC G field with PIC X bytes used for shift out shift in meta character insertion Such a COBOL definition might look like 01 MY_RECORD 05 SO PIC X 05 MY_SBCS_DATA PIC G 52 05 SI PIC X This is not processed correctly by PGAU because all three fields are defined and consequently treated as separate data items when conversion is performed To be properly processed the definition input to PGAU should be 01 MY_RECORD 05 MY_MBCS_DATA PIC G 51 The PGAU REDEFINE DATA statement can redefine the 3 field definition to the 1 field definition by specifying USAGE SKIP on fields SO and SI and 05 MY_MBCS_DATA IC G 51 to redefine MY_MBCS_DATA The three REDEFINE statements can be placed in the PGAU input control file and thus the remote host definition need not be altered po Modifying a Terminal Oriented Transaction to Use APPC The remote transaction program must include mapped APPC verbs to initiate communicate and terminate the APPC conversation However when the remote transaction program is terminal oriented the following options are available You can separate the terminal logic from the application and I O logic Once this separation
131. ansaction 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 TPNAME IN VARCHAR2 64 LUNAME IN VARCHAR2 17 B 2 Oracle Database Gateway for APPC User s Guide 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 PGAINTT 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 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 AIX 5L Based System
132. ansaction 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 have to correspond to different PL SQL parameters for example parm6 INand parm7 OUT They could still be exchanged as two parameters on a single TIP call or one parameter each on two TIP calls however Lastly the remote transaction program s remaining three RECEIVE fields are supplied by tip_cal114 parameters 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 Call Correspondence Order Restrictions Each TIP public function first sends all IN parameters before it receives any OUT parameters Thus a remote transaction program expecting to send one field and then receive one field must correspond to separate TIP calls For example tip_callO parmO OUT lt TCP IP SEND outfield from remote TP PGAXFER RPC checks first for parameters to send but finds none and proceeds to receive parameters tip_callI parmI IN gt TCP IP RECEIVE infield to remote TP PGAXFER RPC processes parameters to send and then check
133. appc admin directory on Microsoft Windows or SORACLE_HOME dg4appc admin directory on UNIX based systems for the specific names of the Oracle Sequence Objects used for version number generation If an explicit version number is specified it is presumed to be the version number of an existing definition not a new definition Such explicit references are used when generating a TIP from a specific remote transaction version defining a remote transaction based on a specific data version If no explicit version is specified a The latest highest number is assumed when a definition is being referenced This is the MAX value selected from the VERSION column for all rows with the same definition name not the CURRVAL number a The next NEXTVAL number is assumed when a definition is being added Version numbers might not be contiguous Although version numbers are always increasing multiple versions of a given definition might skip numbers This is because the sequence object is shared for all definitions of the same type TRANSACTION CALL or DATA and sequence object NEXTVAL is not restored in event of an Oracle database transaction ROLLBACK Thus NEXTVAL might be assigned to a different definition before the next version of the same definition Examples of valid definition names DEFINE TRANSACTION CALL DATA payroll new or latest definition payroll_xaction new or latest definition payroll_xaction VERSION
134. application initialization 2 user input and output 3 remote host transaction initialization using the TIP initialization functions with and without overrides 4 remote host transaction control and data exchange using the TIP user functions 4 6 Oracle Database Gateway for APPC User s Guide Client Application Requirements 5 6 7 remote host transaction termination using the TIP termination function exception handling client application termination Steps 3 4 and 5 vary based on the requirements of the remote host transaction One shot remote host transaction client applications must Declare RHT TIP datatypes to be exchanged All client applications must declare variables to be exchanged with the RHTs using TIPs PL SQL datatypes for such variables have already been defined in the TIP corresponding to each RHT and the client application need only reference the TIP datatype in its declaration Refer also to Declaring TIP Variables on page 4 14 for more information Also refer to the TIP content documentation file for the specific TIP RHT for more information about the exact usage of these variables Initialize the RHT using the TIP initialization function The TIP directs the gateway server to initialize a conversation with the desired RHT specifying either default RHT identifying parameters supplied when the RHT was defined in the PG DD and encoded within the TIP when it was generated or override RHT identifying pa
135. aps because a remote host has either removed the field or has yet to include the field SKIP allows an existing data definition to be used even though some fields do not exist at the remote host PL SQL Naming Algorithms Delimiters COBOL special characters in record group and element names are translated when PGAU DEFINE inserts definitions into the PG DD and by PGAU GENERATE when definitions are selected from the PG DD Special characters are translated as follows a hyphen is translated to underscore _ period is deleted Qualified Compound Names PL SQL variable names are fully qualified and composed from a PL SQL record name as the leftmost qualifier corresponding to level 01 or 77 COBOL record name a PL SQL nested record names corresponding to COBOL group names a PL SQL nested fields corresponding to COBOL elements of datatype CHAR or NUMBER corresponding to non repeating COBOL elements D 8 Oracle Database Gateway for APPC User s Guide Conversion TABLE corresponding to COBOL elements which fall within an OCCURS or OCCURS DEPENDING ON group COBOL repeating fields correspond to PL SQL nested RECORDs of TABLE s Note that when referencing PL SQL variables from calling applications the TIP package name must be prefixed as the leftmost qualifier Thus the fully qualified reference to the PL SQL variable which corresponds to a SKILL is
136. as defaults and can be overridden at TIP initialization time This facilitates the use of one TIP which can be used with a test transaction or system and can later be used with a production transaction or system without having to regenerate the TIP The override_Typ record datatype describes the various transaction attributes that can be overridden by the client application The following overrides are currently supported E tranname can be set to override the value that was specified by the TPNAMI parameter of the DEFINE TRANSACTION statement ea oltpname can be set to override the value that was specified by the LUNAM parameter of the DEFINE TRANSACTION statement oltpmode can be set to override the value that was specified by the LOGMODE parameter of the DEFINE TRANSACTION statement netaddr can be set to override the value that was specified by the SIDEPROFILE parameter of the DEFINE TRANSACTION statement In addition to the transaction attributes defined in the PG DD there are two security related parameters conversation security user ID and conversation security password that can be overridden at TIP initialization time The values for these parameters normally come from either the database link used to access the gateway or the Oracle database session There are cases when the Oracle database user ID is not sufficient for accessing the OLTP system Th
137. ation The Procedural Gateway Administration Utility PGAU generates a complete TIP using definitions you provide The client application can then call the TIP to access the remote host transaction Chapter 2 Procedural Gateway Administration Utility discusses the use of PGAU in detail Client Application Development SNA Only 4 1 Overview of Client Application This overview explains what you must do in order to call a TIP and control a remote host transaction The gateway receives PL SQL calls from the Oracle database and issues APPC calls to communicate with a remote transaction program The following three application programs make this possible 1 2 an APPC enabled remote host transaction program a Transaction Interface Package or TIP A TIP is a PL SQL package that handles communication between the client and the gateway and performs datatype conversions between COBOL and PL SQL PGAU generates the TIP specification for you In the shipped samples the PGAU generated package is called pgadb2i pkb This generated TIP includes at least three function calls that map to the remote transaction program pgadb2i_init initializes the conversation with the remote transaction program pgadb2i_main exchanges application data with the remote transaction program pgadb2i_term terminates the conversation with the remote transaction program Refer to Appendix E Tip Internals for more information about TIPs if y
138. ation and Configuration Guide for Microsoft Windows for more information about these parameters Rerun the client application and examine the trace see the next step for details To disable the trace reset SET TRACE_LEVEL 0 Examine the trace output The TIP trace output can be saved in a spool file such as spool tipname trc TIP trace output is written to a named DBMS_PIPE and can be retrieved under SQL Plus by issuing the following command exec rtrace tipname or it can be purged by issuing the following command exec ptrace tipname Note tipname is case sensitive and must be specified exactly as it is in the TIP Troubleshooting 8 9 Gateway Server Tracing Gateway server trace output is written to a log file in a default directory path specified by the SET LOG_DESTINATION gateway parameter in SORACLE_HOME dg4appc admin initsid ora for Microsoft Windows and in SORACLE_HOME dg4appc admin initsid ora for UNIX based systems For example on Microsoft Windows D G SET LOG_DESTINATION C oracle pga 11 2 dg4appc log On UNIX based systems SET LOG_DESTINATION ORACLE_HOME dg4appc log Refer to Gateway Server Tracing on page 8 10 for more information The gateway server log file can be viewed be editing the file or by issuing other system commands that display file contents The log file can also be copied and saved to document problem symptoms Ga
139. attr table A 7 pga_trans_calls table A 9 pga_trans_values table A 8 pga_usage A 5 pga_usage constant A 5 PGAADMIN 3 1 pgacics sql 1 11 pgadb2i file E 1 pgadb2id sql file 4 4 4 20 pgadb2i pkb 1 6 pgadb2i pkb file 1 6 1 13 4 2 4 4 pgadb2i pkh file 1 6 1 13 pgadb2i sql file 4 4 E 1 pgaims file E 1 pgaims sql 1 15 PGAINIT 1 9 B 1 role in mapping SNA parameters to TCP IP 6 1 PGAINIT function 1 4 1 9 PGATCTL B 6 PGATERM B 5 PGATERM function 1 4 1 9 PGATRAC B 6 PGAU 41 accesses definitions in PG DD 1 5 commands also called statements 2 6 COMMIT processing 2 2 defining and testing a TIP 2 4 definition 2 1 Index 5 used to generate TIP specifications 1 5 definition names 2 4 definition versioning 2 5 definitions 2 3 functions 2 2 generated TIP specifications 1 8 generation 2 3 interpretation of COBOL symbols in datatype conversion D 3 invoking 2 3 keywords 2 5 overview 2 1 purpose of PGDL 1 4 role in calling TIPs on gateway using TCP IP 7 1 ROLLBACK processing 2 2 sample input F 1 writing statements 3 4 PGAU commands 1 12 1 17 CONNECT 2 3 2 6 CONNECT parameters 2 6 DEFINE CALL 2 7 2 25 3 4 4 23 call list 3 2 on gateway using SNA 1 13 on gateway using TCP IP 1 18 sample F 2 DEFINE DATA 2 8 2 25 3 4 4 10 4 23 7 4 A 11 on gateway using SNA 1 12 on gateway using TCP IP 1 18 parameters 2 8 sample F 1 DEFINE DATA datatype conversions USAGE ASI
140. ay during the PREPARE phase The PGA_CC_PEND GLOBAL _ TRAN D ING table contains the following columns This is the Oracle Global Transaction ID for the transaction It is identical to the corresponding column in the DI m SIDE_NAME BA_2PC_PENDING table This is the Side Information Profile name that was used by the gateway to allocate the APPC conversation with the target LU It corresponds to the LU_NAME SIDENAME parameter passed to the PGAINIT gateway function This is the fully qualified partner LU name of the target LU This value is either the LU name from the Side Information Profile or the LUNAME parameter passed to the PGAINIT gateway function This name fully identifies the OLTP system on which the transaction was executed a MODE_NAME This is the Mode name that was used by the gateway to allocate the APPC conversation with the target LU The value is either the Mode name from the Side Implementing Commit Confirm SNA Only 5 7 Commit Confirm Flow Information Profile or the MODENAME parameter passed to the PGAINIT gateway function a TP_NAME This is the transaction program name executed at the target LU The value is either the TP name from the Side Information Profile or the TPNAME parameter passed to the PGAINIT gateway function This name fully identifies the OLTP transaction prog
141. bles 5 7 gateway server trace 8 10 8 11 GENERATE 2 2 GENERATE statement command 1 13 1 18 3 5 3 7 4 10 7 4 E 2 F 2 GLOBAL_TRAN_ID 5 7 Globalization Support multi byte character set support 4 25 7 15 granting privileges for creating TIPs 3 1 GROUP statement PGAU 3 7 H HOST command 2 19 implicit APPC 4 27 implicit versioning sample definitions F 3 IMS 1 1 communication with Integrating Server using TCP IP 1 15 IMS inquiry location of sample file 1 7 IMS TM communication through the gateway 1 1 initialization files see gateway initialization files also see PGA parameters initiating remote transactions 1 9 initsid ora file 1 3 8 10 8 11 parameters to run pg4tcpmap tool 6 5 I O PCB 1 15 3 2 7 2 Index 3 J JUSTIFIED D 5 JUSTIFIED LEFT D 5 JUSTIFIED RIGHT D 5 K keywords PGAU 2 5 L LENGTH IS field 2 D 6 logging server 5 3 5 5 description 5 5 interaction with gateway database 5 5 LU_NAME 5 7 MAKE_NUMBER_TO_RAW_FORMAT function C 6 MAKE_RAW_TO_NUMBER_FORMAT function C 5 mapping parameters from SNA to TCP IP 6 1 mapping table PGA_TCP_IMSC 1 16 MBCS See multi byte character sets MODE_NAME 5 7 multi byte character sets MBCS 4 25 7 15 application development support 4 25 7 15 multi conversational transaction type for gateway using SNA 1 10 multi conversational transactions 4 5 4 9 N non persistent socket transaction type for
142. byte character sets DBMS_PIPE PL SQL package 3 1 debugging tool PGATRAC function B 6 DEFINE CALL 2 2 DEFINE CALL parameters 2 7 DEFINE CALL statement command 1 13 1 18 3 4 4 23 F 2 DEFINE DATA 2 2 DEFINE DATA statement command 1 12 1 18 2 25 3 4 4 10 4 23 7 4 A 11 F 1 DEFINE TRANSACTION parameters 2 10 DEFINE TRANSACTION statement command 3 5 4 23 F 2 defining and generating a TIP 3 6 definition versioning 2 5 deleting and inserting rows into PGA_TCP_IMSC table 6 6 DESCRIBE command 2 13 dg4pwd utility definition 1 4 recommended security utility feature 1 4 DISCONNECT command 2 13 double byte character sets DBCS in application development 4 25 7 15 driver procedure on gateway using SNA 1 14 on gateway using TCP IP 1 19 E EBCDIC automatic conversion 1 3 environment dictionary sequence numbers A 1 errors causes of 8 1 data conversion 8 4 including exception handlers in your TIP 4 20 7 14 NUMBER_TO_RAW function C 5 PLS 00123 program too large 4 23 truncation 8 8 examples APPC conversation sharing 4 23 EXECUTE command 2 14 executing client application development 4 20 7 14 EXIT command 2 14 F file initsid ora 1 3 8 10 8 11 pagaims E 1 pgadb2i E 1 pgadb2id sql 4 20 pgadb2i pkb 1 6 1 13 4 2 4 4 pgadb2i pkh 1 6 1 13 4 4 pgadb2i sql E 1 pgau trc 2 16 2 18 pgddausr sql 4 27 7 16 pgddcr8 sql 2 5 A 5 pgtflipd sql 7 14 E 1
143. 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 database to recompile such dependent client applications If your gateway is using the SNA communication protocol issue the following Tip Internals E 3 PL SQL Package and TIP File Separation SQL gt column ddl_date format A22 heading LAST_DDL SQL gt 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 PGADB21I PACKAGE NOV 24 1999 09 09 13 VALID PGADB21I 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 If your gateway is using the TCP IP communication protocol issue the following SQL gt column ddl_date format A22 heading LAST_DDL SQL gt 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 PGTFLIP PACKAGE APR 24 03 03 04 58 VALID PGTFLIP PACKAGE BODY APR 24
144. cation tipname Is the PL SQL package TIP name as stored in Oracle database This is the same value as in the statement CREATE or REPLACE PACKAGE tipname in the TIP specification J tran_rectype Is the PL SQL record datatype declared in the tipname TIP specification This is the same value as in the TYPE tran_rectype is RECORD statement Refer to the tipname doc content file for a complete description of the user declarations you can reference The client application calls the TIP public function as if it were any local PL SQL function rc tip_calll tranuse appl_var appl_record Client Application Development TCP IP Only 7 9 Calling the TIP from the Client Application In the TCP IP IMS Connect example the PL SQL driver pgt lipd sql which is located in SORACLE_HOME dg4appc demo IMS directory on Microsoft Windows and in SORACLE_HOME dg4appc demo IMS directory on UNIX based systems is the client application and includes the following declaration T CREATE or REPLACE PROCEDURE pgtflipd mesgin IN CHAR IS trannum INTEGER 0 transaction usage number E mesgout VARCHAR2 254 the output parameter Xy rc INTEGER 0 PGA RPC return codes 8 term INTEGER 0 1 if pgtflip_term called Initializing the Conversation The call to initialize the conversation serves several purposes a To cause the PL SQL package the TIP to be loaded and to
145. ccssccscsssssesesescscsssesesescsesssesescsescseseseecsesssnsneceeeees 4 23 APPC Conversation Sharing Overrides and Diagnostics ccccsccesesceceseseseststeeseseeseeseeeans 4 25 Application Development with Multi Byte Character Set Support eee 4 25 Modifying a Terminal Oriented Transaction to Use APPC cccec cee eeceeeeeeenecetenenenes 4 26 Privileges Needed to Use TIPS oi bib 4 27 Implementing Commit Confirm SNA Only Overview of Commit ConfirM ooocinnncncnnnnonicinnnonononcnononanononononconononn no nono no nono nono ona nano corrio a nora re ronca recio 5 1 Supported OLTPS cui ias 5 2 Components Required to Support Commit ConfirM ooooicicicinonocininnononennonanonincininnonin coco nnonananananonono 5 2 Application Design Requirements oooconicinnnnnnocononinonacinonanononononanonononononanononononononononon oran onononononanonononcnos 5 4 vi Commit C nfirm Architecture A A a dades 5 4 COMIPONENES arnser eea AAA ERA LA AAA AAA A 5 5 TiNnteTACH ONS A RR 5 5 C mmit Confirm Flow iaa incas 5 5 Commit Confirm Logic Flow Step by Step cococicicicococoninnnononacnonarananononananananonononanononononcnanonononononos 5 6 Gateway Server Commit Confirm Transaction Log eococoonenennncnnnnonncncnrnnnorarnnnnnnnennneroranannnnnnos 5 7 PG4TCPMAP Commands TCP IP Only Preparation for Populating the PGA_TCP_IMSC Table ooooociciconnccnnoninnconnoninonananonncnnncnnonononancnncnos 6 1 Overview ni ih nei eae deie a ia 6 1 Po
146. ce in PL SQL Max length gt PL SQL variable length version number 9 0 Version number of this entry Set from an Oracle sequence object for data version inserted into the PGADD updtdate date Audit trail date time this control record last updated updtuser varchar2 30 Audit trail user id program which last updated this record usage varchar2 6 Default usage of this data item PASS SKIP NULL ASIS Used primarily by PGAU REPORT Max length gt 4 char string length Database Gateway for APPC Data Dictionary A 11 PG DD Active Dictionary Table A 19 Cont pga_data Column Type Content data number 9 0 Data definition number Foreign key pga_call_parm data pga_field data Set from an Oracle sequence object pga_fields The pga_fields table defines each field within a data item and relates the remote host data field to its PL SQL variables or nested records Each field item might have attributes related to it by field in the pga_data_attr and pga_data_values tables One row exists in the pga_fields table for each atomic item field clause or nested record defined by a PGAU D EFIN E DATA statement Several rows would exist related by a single data and incrementing fld to define an aggregate data item one row per field or group Table A 20 presents the column type and content information for pga_fields Table A 20 pga_fields Column Type data number 9
147. cle Education courses Oracle Consulting services and Oracle Support Services from the Web site In addition Oracle provides free trial software updates on Oracle products and service and technical brochures and data sheets Oracle Support Services Technical Support registration and contact information worldwide is available at the following address http www oracle com support At Oracle s support site you will find templates to help you prepare information about your problem before you call so that you may be helped more quickly You will also need your CSI number if applicable or complete contact details including any special project information Oracle Technology Network OTN delivers all product documentation as well as technical papers code samples self service developer support and Oracle s key developer products to enable rapid development and deployment of applications built on Oracle technology Register with the Oracle Technology Network OTN at xiii xiv http otn oracle com All Oracle product documentation can be found at http otn oracle com documentation My Oracle Support My Oracle Support is Oracle s web service for technical information Members of My Oracle Support can search for updates alerts patches and other information about products releases and operating systems or set preferences to be notified automatically of new information My Oracle Support offers a variety of servic
148. cpath is the optional directory path of the TIP specification and Sp Sp bo the TIP content documentation It defaults to the current directory The value must end with a backslash for Microsoft Windows and a slash for UNIX based systems ecname is the filename of the TIP specification and the TIP content documentation It defaults to pname if specified or else pgau ectype is the optional file extension of the TIP specification and defaults to pkh dypath is the optional directory path of the TIP body It defaults to specpath if specified or else the current directory The value must end with a backslash for Microsoft Windows and a slash for UNIX based systems Procedural Gateway Administration Utility 2 15 PGAU Commands Table 2 5 Cont GENERATE Parameter Descriptions Parameter Description bodyname is the optional file name of the TIP body It defaults to specname if specified or else pname if specified or else pgau If bodyname defaults to specname the leftmost period of specname is used to extract bodyname when specname contains multiple qualifiers bodytype is the optional file extension of the TIP body and defaults to pkb The TIP Content output path defaults to specpath or else the current directory The file id defaults to specname if specified or else pname if specified or else pgau and always has an extension of doc Refer to the GENERATE Usage Notes on page 2 18
149. cription DATA dname is a mandatory parameter It is the name of the data definition to be modified 2 20 Oracle Database Gateway for APPC User s Guide PGAU Commands Table 2 6 Cont REDEFINE DATA Parameter Descriptions Parameter Description VERSion datavers is an optional parameter It specifies which version of dname is to be modified and if specified the updated dname information retains the same version number a new version is not created It defaults to the highest version if omitted PLSDNAME plsdvar is an optional parameter It is the name of the PL SQL variable associated with the dname above It becomes the name of a PL SQL variable if the dname item is atomic data or a PL SQL record variable if the dname item is aggregate data such as a record or structure when the TIP is generated This name replaces any p1sdvar name previously specified by DEFINE DATA into pga_data plsdvar of the PG DD FIELD fname is an optional parameter It is the name of a field or group within the dname item if aggregate data is being redefined such as changing a field within a record PLSFNAME plsfvar is an optional parameter if FIELD is specified It is the name of the PL SQL variable associated with the fname above It becomes the name of a PL SQL field variable within a PL SQL record variable when the TIP is generated This name replaces any plsfvar name previously specified by REDEFINE DATA into pga_data plsfvar
150. cute on tipname to tip_user_userid where database_specification_string is the Oracle Net identifier for the Oracle database where the gateway UTL_RAW and UTL_PG components were installed This is the same Oracle database where the TIPs are executed and where grants on the TIPs are performed from the TIP owner user ID A SQL script for performing these grants is provided in the SORACLE_HOME dg4appc admin directory on Microsoft Windows and in the SORACLE_HOME dg4appc admin directory on UNIX based system The pgddausr sql script performs the grants for private access to the packages by a single TIP user If private grants are to be used the pgddausr sql script must be run once for each TIP user s user ID Client Application Development SNA Only 4 27 Privileges Needed to Use TIPs To run these scripts use SQL Plus to connect to the Oracle database as user PGAADMIN From SQL Plus run the pgddausr sal script from the SORACLE_HOME dg4appc admin directory on Microsoft Windows or SORACLE_HOME dg4appc admin directory on UNIX based system The script performs the necessary grants as previously described You are prompted for the required user IDs passwords and database specification strings If you are using private grants repeat this step for each user ID requiring access to the packages No script has been provided to perform public grants To do this issue the following commands For Microsoft Windows C g
151. d using PGAU DEFINE DATA Simple data items such as single numbers or character strings and complex multi field data aggregates such as records or structures can be defined PGAU automatically generates equivalent PL SQL variables and records of fields or tables for the client application to reference in its calls to the generated TIP As discussed a parameter might be a simple data item such as an employee number or a complex item such as an employee record PGAU DEFINE DATA automatically extracts the datatype information it needs from the input program data definition files In this example FLIPIN and FLIPOUT are the arguments to be exchanged PGTFLIP_MAIN trannum FLIPIN FLIPOUT APGAU DEFINE DATA statement must therefore be issued for each of these parameters DEFINE DATA FLIPIN PLSDNAME FLIPIN USAGE PASS LANGUAGE IBMVSCOBOLIT 01 MSGIN PIC X 20 i DEFINE DATA FLIPOUT PLSDNAME flipout USAGE PASS LANGUAGE IBMVSCOBOLIT 01 MSGOUT PIC X 20 Jas Note that a definition is not required for the trannum argument This is the APPC conversation identifier and does not require a definition in PGAU CALL Correspondence The requirement to synchronize TCP IP send and receive means that when the remote transaction program expects data parameters to be input it issues TCP IP receive to read the data parameters Accordingly the TIP must cause the gateway to Clie
152. d PGDL Procedural Gateway Definition Language This appendix contains the following section Calling Gateway Functions to Execute Transaction Programs on page B 1 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 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 parml 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 Gateway RPC Interface B 1 Calling Gateway Functions to Execute Transaction Programs user ID and password Upon successful completion of either function the conversation is ready to send data to the remote tr
153. d above to determine the source of the problem These files are loaded into the SORACLE_HOME dg4appc admin directory on Microsoft Windows or SORACLE_HOME dg4appc admin directory on UNIX based systems during installation Data Conversion Errors Data conversion errors are usually the result of a incorrect determination of datatype or incorrect specification of data position PGAU determination of the datatype is based on the values found in the PG DD pga_fields mask and pga_fields maskopts columns PGAU generates PL SQL code to perform conversions based on the mask value PIC Xconverted to CHAR with the same character length PIC G converted to CHAR with the same character length PIC 9 converted to NUMBER Character datatype is presumed for all PIC Xand PIC G mask values and conversion errors are more likely the result of position length and justification errors Determination of numeric datatype depends on several factors including the combination of mask and maskopts values and how they apply to the actual remote host data in its internal format Values for mask maskopts and data might conflict in unexpected ways For example an option such as USAGE IS COMP might be overridden if the data is in display format While compilers occasionally perform such overrides correctly they can cause unexpected results when exchanging data with systems coded in other languages To notify the user of such ov
154. d in the gateway and remote host 1 8 Oracle Database Gateway for APPC User s Guide RPC Functions TIP Function Table 1 1 RPC Functions and Commands in the Gateway and Remote Host Applications Oracle TIP Gateway Remote Host call tip_init tip_init PGAINIT Initiate program call pgainit gateway call tip_main tip_main PGAXFER Exchange data call pgaxfer gateway call tip_term tip_term PGATERM Terminate program call pgaterm gateway The following sections describe how a TIP works by first establishing a connection to the remote host then exchanging data from the target transaction program and finally terminating a conversation Remote Transaction Initiation The TIP initiates a connection to the remote host using one of the gateway functions PGAINIT When the communication protocol is SNA PGAINIT provides as input the required SNA parameters to start a conversation with the target transaction program These parameters are sent across the SNA network which returns a conversation identifier to PGAINIT Future calls to the target program use the conversation identifier as an input parameter When the communication protocol is TCP IP PGAINIT provides as input the required TCP IP parameters These parameters are sent across the TCP IP network to start the conversation with the target transaction program The TCP IP network returns a socket file descriptor to PGAINIT Future calls
155. data number 9 0 Data definition in pga_data data of this item Foreign key pga_data data pga_data_values data Copied from pga_data data for the data item when this call parm definition was inserted or updated pga_data The pga_data table defines each data item used as a parameter in a call and relates the remote host data name to its PL SQL variables and any component subfields or clauses within each data item if the data item is an aggregate such as a record Each data item might have attributes related to it through its corresponding field definition Even atomic data items have a single row in the pga_field table One row exists in the pga_data table for each data item defined by a PGAU D DATA or REI DEF INE T FINE DATA statement Table A 19 presents the column type and content information for pga_data Table A 19 pga_data Column Type Content comp number 9 0 Compiler id number Foreign key pga_compiler comp Set from pga_compiler comp based on the language parameter specified on the DEFINE DATA statement when the data definition is inserted compopts varchar2 100 Compiler options from the COMPOPTS keyword on the DEFINE DATA statement dname varchar2 255 Name from the DEFINE statement Primary key Max length gt COBOL name length plsdvar varchar 30 PL SQL variable name of data item for referen
156. ddress technical obstacles so that our documentation can be accessible to all of our customers For more information visit the Oracle Accessibility Program Web site at http www oracle com accessibility Accessibility of Code Examples in Documentation Screen readers may not always correctly read the code examples in this document The conventions for writing code require that closing braces should appear on an otherwise empty line however some screen readers may not always read a line of text that consists solely of a bracket or brace xi Accessibility of Links to External Web Sites in Documentation This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites Deaf Hard of Hearing Access to Oracle Support Services To reach Oracle Support Services use a telecommunications relay service TRS to call Oracle Support at 1 800 223 1711 An Oracle Support Services engineer will handle technical issues and provide customer support according to the Oracle service request process Information about TRS is available at http w fcc gov cgb consumerfacts trs html and a list of phone numbers is available at http www fcc gov cgb dro trsphonebk html Related Documents The Oracle Database Gateway for APPC User s Guide is included as part of your product shipment Also included i
157. den by the NLS_LANGUAGE parameter of DEFINE TRANSACTION It is an Globalization Support name in the language_ territory charset format It specifies the Globalization Support name in which the remote host data for the specific character field being redefined is encoded The field can be single byte or multi byte character data Procedural Gateway Administration Utility 2 21 PGAU Commands Table 2 6 Cont REDEFINE DATA Parameter Descriptions Parameter Description LOCAL LANGUAG nlsname El LANGUAGE language definition INFILE filespec is an optional parameter The default value is initialized from the LANGUAGE variable of the local Oracle database when the TIP executes Itis an Globalization Support name in the language_territory charset format It specifies the Globalization Support name in which the local Oracle data for the specific character field being redefined is encoded The field can be single byte or multi byte character data is a mandatory parameter if definition input is specified It specifies the name of the programming language in the supplied definition PGAU presently supports only COBOL is mutually exclusive with the INFILE parameter Itis an inline description of the data The description must be provided in COBOL syntax This inline description must begin with an opening parenthesis and end with a closing parenthesis The opening parenthesis must be the last non b
158. e Procedure Calls PG DD Client D Data Dictionary PGAU SNA or TCP P aa eae Mainframe t 4 aaa l OLTP l Remote l l Transaction Program l I Examples and Sample Files for the Gateway The following sample files and examples are referred to for illustration purposes throughout this guide There are different example and sample files for a gateway using the SNA protocol than for a gateway using TCP IP for IMS Connect Examples and Sample Files for Gateway Using SNA For gateways using the SNA communication protocol this guide uses a CICS DB2 inquiry as an example Transaction Interface Packages TIPs pgadb2i pkb and pgadb2i pkh send an employee number empno to a DB2 application and receive an employee record emprec The CICS DB2 inquiry sample and its associated PGAU commands are also available in the 3ORACLE_HOME dg4appc demo CIcs directory on Windows platform and SORACLE_HOME dg4appc demo CICS directory on UNIX platforms The sample CICS DB2 inquiry used as an example in this chapter is in files pgadb2i pkh and pgadb2i pkb Refer to the README doc file in the same directory for information about installing and using the samples It can be found in the SORACLE_HOME dg4appc demo CICs directory for Windows and SORACLE_HOME dg4appc demo CICS directory for UNIX G E Examples and Sample Files for Gateway Using TCP IP If
159. e Columns Column Name Type Content SideProfileName varchar2 8 HostName varchar2 169 NOT NULL PortNumber varchar2 17 NOT NULL ANDRS char 1 NOT NULL 6 2 Oracle Database Gateway for APPC User s Guide This parameter has no SNA implication It is simply a name that is defined in the ct1 file for the PGAU utility It represents a group of IMS transactions with similar IMS Comnect attributes such as time delay socket type and IMS subsystem ID Unique index The OLTP TCP IP address or the hostname The OLTP port number ANDRS specifies whether the client is sending A ACK Positive Acknowledgement N NAK Negative Acknowledgement D DEALLOCATE Deallocate Connection R RESUME Resume TPIPE S SENDONLY Send only Acknowledgment or Deallocate blank no request for Acknowledgement or Deallocate The default is blank Populating the PGA_TCP_IMSC Table Table 6 1 Cont PGA_TCP_IMSC Table Columns Column Name Type Content TIMER char 1 NOT Time delay for the receive to the NULL datastore after an ACK or RESUME TPIPE D default value X 00 25 second S short wait X 01 through X 19 01 to 25 second N No Wait occurs I Receive waits indefinitely The default is D SOCK char 1 NOT Socket Connection Type NUn T Transaction Socket P Persistent Socket N Non persistent Socket The default i
160. e Implicit Versioning Definitions Table F 1 provides a description of the TIP user transaction datatypes in package name PGADB21 Table F 1 TIP User Transaction Datatypes Used in Package Name PGADB2I Datatype Description PGADB21I EMPNO is a PL SQL variable corresponding to COBOL EMPNO PGADB21 DCLEMP Which is a PL SQL RECORD corresponding to COBOL DCLEMP PGADB2I DB2 Which is a PL SQL RECORD corresponding to COBOL DB2INFO and the application calls PGADB21 PGADB21_INIT trannum PGADB21 PGADB2I_MAIN trannum empno emprec PGADB21 PGADB21_DIAG trannum db2 PGADB21 PGADB21_TERM trannum termtype Sample Implicit Versioning Definitions The examples are sample definitions of DATA CALL and TRANSACTION entries with implicit versioning This example creates a new DATA version of EMPREC because EMPREC DATA was defined previously DEFINE DATA EMPREC PLSDNAME NEWEMP USAGE PASS LANGUAGE IBMVSCOBOLIT INFILE emp2 cob where the file emp2 cob contains the following 01 NEWEMP 10 EMPNO PIC X 6 10 FIRSTNME 49 FIRSTNME LEN PIC S9 4 USAGE COMP 49 FIRSTNME TEXT PIC X 12 10 MIDINIT PIC X 1 10 LASTNAME 49 LASTNAME LEN PIC S9 4 USAGE COMP 49 LASTNAME TEXT PIC X 15 10 WORKDEPT PIC X 3 10 PHONENO PIC X 3 10 HIREDATE PIC X 10 10 JOB PIC X 8 10 EDLEVEL PIC S9 4 USAGE COMP 10 SEX PIC X 1 10 BIRTHDA
161. e TIP defaults an additional client application record variable must be declared as override_Typ datatype values must be assigned to the override subfields and the override record variable must be passed on the TIP initialization call from the client application For example my_overrides pgadb2i override_Typ declaration my_overrides oltpname CICSPROD swap to production CICS my_overrides tranname TNEW new transaction name BEGIN rc pgadb2i pgadb2i_init tranuse my_overrides init Within the TIP override attributes are checked for syntax problems and passed to the gateway server Security Considerations The security requirements of the default and overridden OLTPs must be the same because the same gateway server is used in either conversation as dictated by the database link names in the PGA RPC calls The gateway server startup security mode is set at gateway server initialization time and passed unchanged to the OLTP at TIP or conversation initialization time Exchanging Data The client application should pass the transaction instance number returned from a previous tip_init call to identify which remote transaction program is affected and to identify any client application data parameters to be exchanged with the remote transaction program In this CICS DB2 inquiry example we pass an employee number and receive an employee record back rc pgadb2i pgadb2i_main tranuse transfer data em
162. e TIP schema name on TIP user calls the client application specifies to which RHT the call is being made tranuse IN OUT parameter value when multiple instances of the same TIP RHT are being controlled This is the value returned on the TIP initialization function call and subsequently passed as an IN parameter on the user defined TIP function calls The returned tranuse value corresponds to that conversation connected to a given instance of an RHT By supplying the same tranuse value on TIP user calls the client application specifies to which RHT instance the given RHT call is being made Client application logic must keep track of which RHTs have been started and which TIPs and tranuse values correspond to started RHTs Exchange data with each RHT using the TIP user function s either once or repetitively if the RHT is one shot or persistent Client application logic must sequence the RHTs though their allowed steps in accordance with proper RHT operation as does a user operating the RHTs interactively Client application logic must also perform any cross RHT result analysis or data transfer that might be required All TIPs execute in isolation from each other Output from one RHT intended as input to another RHT must be received in the client application as an IN or IN OUT parameter from the first RHT and sent as an IN or IN OUT parameter from the client application to the second RHT All TIP to RHT function calls must be performed by t
163. e byte character sets DBCS for PIC G datatypes PGAU processes IBM VS COBOLII PIC G datatypes as PL SQL VARCHAR2 variables and generates TIPs which automatically convert the data according to the Oracle NLS_LANGUAGEs specified for the remote host data and the local Oracle data These Oracle NLS_LANGUAGEs can be specified as defaults for all PIC G data exchanged by the TIP with the remote transaction see DEFINE TRANSACTION REMOTE_MBCS or LOCAL_MBCS The Oracle NLS_ LANGUAGES for any individual PIC G data item can be further overridden see REDEFINE DATA REMOTE or LOCAL_LANGUAGE DBCS data can be encoded in any combination of supported DBCS character sets For example a remote host application which allows different codepages for each field of data in a record is supported by the Oracle Database Gateway MBCS support Use of REDEFINE DATA REMOTE_LANGUAGE or LOCAL_LANGUAGE on PIC X items is also supported Thus a TIP can perform DBCS or MBCS conversions for specified PIC X data fields in addition to SBCS conversions by default for the remaining PIC X data fields Default SBCS conversion is according to the DEFINE TRANSACTION NLS_LANGUAGE and local Oracle default LANGUAGE environment values When PGAU is generating a TIP the PIC G datatypes are converted to PL SQL VARCHAR2 datatypes After conversion by the TIP received PIC G
164. e indicated entry and is mutually exclusive with ALL Reports the PG DD contents for all existing versions of every transaction entry or optionally a specific transaction tname and is mutually exclusive with TRANSACTION Reports the PG DD contents for all existing versions of every call entry or optionally a specific call cname and is mutually exclusive with CALL Reports the PG DD contents for all existing versions of every data entry or optionally a specific data dname and is mutually exclusive with DATA Reports call entries associated with the specified transactions Reports data entries associated with the specified calls and when specified for transactions implies WITH CALLS Reports PG DD column values for tran cal1 parm data and attr as appropriate depending on the type of items being reported This report is useful with TIPs generated with PG DD Diagnostic references Refer to the GENERATE DIAGNOSE PGEX OR option for more information 2 24 Oracle Database Gateway for APPC User s Guide PGAU Commands Table 2 7 Cont REPORT Parameters Descriptions Parameter Description ISOLATED Mutually exclusive with all other parameters All unreferenced CALL and DATA entries are reported along with TRANSACTIONS that reference missing CALLs and DATA and CALLs that reference missing DATA REPORT Usage Notes Report output is to the terminal and can be spooled saved and pr
165. e indicates book titles emphasis or placeholder variables for which you supply particular values monospace Monospace type indicates commands within a paragraph URLs code in examples text that appears on the screen or text that you enter Accessing Installed Documentation Documentation for Oracle Database Gateway for APPC Documentation for this product includes this guide and the Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows and the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 To access the documentation in HTML and PDF formats use a browser to open the top level of the Gateway Documentation Library included on your installation media This level contains links to product and Windows specific documentation Oracle Product Documentation Oracle Databasel1lg product documentation is on the Oracle Database 11g Platform Specific Documentation Library included on your installation media Instructions for accessing and installing the documents on the library are found in the README file on the top level directory of the installation media Oracle Services and Support Oracle s corporate web page is at the following address http www oracle com Oracle offers a wide range of services to help facilitate corporate system solutions including Ora
166. e is included the name must be specified within double quotes Names are assumed to be unique within the PG DD except when duplicate names are intentionally distinguished by a unique version number It is your responsibility to ensure name uniqueness Valid characters for PG DD definition names are A through Z a through z a 0 through 9 _ underscore Note that unless defaults are overridden transaction definition names might be PL SQL package names and transaction call names might be PL SQL procedure names Therefore choose names that are syntactically correct for PL SQL making certain that they are also unique names within that system As the user it is your responsibility to ensure PL SQL name compatibility 2 4 Oracle Database Gateway for APPC User s Guide Process to Define and Test a TIP Definition Versioning Keywords The PG Data Dictionary tables contain the descriptions of transactions and data structures There might be more than one version of a definition Old versions are retained indefinitely In all PG DD operations a definition or package is referred to by its name That name can be qualified by a specific version number All version numbers are supplied by Oracle Sequence Objects are purely numeric must be free from user alteration suffixing or prefixing Refer to Appendix A Database Gateway for APPC Data Dictionary and the pgddcr8 sql file in the 3ORACLE_HOME dg4
167. e so that the forget recovery transaction can use the Oracle Global Transaction ID to directly access a log entry Note If your OLTP is IMS TM you must add a PCB for the commit confirm transaction log database to the PSB for each transaction that you will use with a commit confirm gateway This PCB must be the first PCB in the PSB Commit Confirm Architecture The architecture of the commit confirm implementation in the Oracle Database Gateway for APPC consists of three main components Oracle database Oracle Database Gateway for APPC server gateway server 5 4 Oracle Database Gateway for APPC User s Guide Commit Confirm Flow Components Interactions a Logging server an Oracle database holding the tables PGA_CC_PENDING and PGA_CC_LOG This section describes the role each component plays in the operation of commit confirm and how these components interact The Oracle database is the controlling component in the commit confirm architecture It tells the gateway server when to commit a transaction and when to rollback a transaction It does the same with all other servers participating in a distributed transaction When a failure has occurred it is the Oracle database acting as the integrating server which drives the recovery process in each participating server including the gateway server The gateway server performs the task of converting instructions from the Oracle database into LU6 2 operations a
168. e too large to compile This TIP does not use APPC conversation sharing as there is only the one TIP rht ABC The RHTs do however perform their normal sharing of the conversation at the remote host If the TIP was small enough to compile the client application calls TIP functions as follows re rhtABC rhtABC_init tranuse rc rhtABC pick tranuse choice rc rhtABC query tranuse input answer rc rhtABC update tranuse record rc rhtABC select tranuse record rc rhtABC rhtABC_term tranuse Example 2 This example demonstrates defining a set of TIPs with APPC conversation sharing separating the functions of RHTs A B and C into three TIPs DEFINE TRANSACTION rhtA calls menu_A tpname RETA DEFINE TRANSACTION rhtB calls query_B tpname RHTA DEFINE TRANSACTION rhtC calls update_C select_C tpname RHTA Each TIP includes only the call and data it requires and each TIP automatically performs APPC conversation sharing The client application calls these functions as follows rc rhtA rhtA init tranuse rc rhtA pick tranuse choice rc rhtB query tranuse input answer rc rhtC update tranuse record rc rhtC select tranuse record rc rhtB rhtB_term tranuse The only client application difference between the two examples is in the schema qualifier on each of the TIP calls This is because the function being called is in a different TIP which has a diffe
169. e user ID and password overrides provide a way to specify those parameters to the OLTP system The following overrides are currently supported a Oltpuser can be set to override the user ID used to initialize the conversation with the OLTP oltppass can be set to override the password used to initialize the conversation with the OLTP The security overrides have an effect only if PGA_SECURITY_TYPE PROGRAM is specified in the gateway initialization file and the OLTP system is configured to accept a user ID and password on incoming conversation requests The transync APPC SYNCLEVEL and trann1s Globalization Support character set are defined in the override record datatype but are reserved for future use The RHT SYNCLEVEL and Globalization Support name cannot be overridden The client application might override the default attributes at TIP initialization for the following reasons a to start a different version of the RHT such as production instead of test 4 18 Oracle Database Gateway for APPC User s Guide Exchanging Data to change the location of the OLTP containing the RHT if the OLTP was moved due to migration or a switch to backup configuration Client applications requiring overrides can use any combination of override and initialization parameters and might alter the combination at any time without regenerating the TIP or affecting applications that do not override parameters To override th
170. each use The warning message is documented in the Oracle Database Error Messages manual This parameter must be allocated and passed as a parameter in all cases regardless of how wind is specified RAW_TO_NUMBER RAW_TO_NUMBER converts a RAW byte string r from the remote host internal format specified by mask maskopts envrnmnt compname compopts and nlslang into an Oracle number Warnings are issued if enabled when the conversion specified conflicts with the conversion implied by the data or when conflicting format specifications are supplied For detailed information about the mask maskopts envrnmnt compname and compopts arguments refer to NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values on page C 11 Syntax function RAW_TO_NUMBER r IN RAW mask IN VARCHAR2 maskopts IN VARCHAR2 envrnmnt IN VARCHAR2 compname IN VARCHAR2 compopts IN VARCHAR2 nlslang IN VARCHAR2 wind IN BOOLEAN wmsgbsiz IN BINARY_INTEGER wmsgblk OUT RAW RETURN NUMBER Where Table C 3 describes the parameters in this function Table C 3 RAW_TO_NUMBER Function Parameters Parameter Description r is the remote host data to be converted mask is the compiler datatype mask maskopts are the compiler datatype mask options or NULL envrnmnt is the compiler environment clause or NULL compname is the compiler name compopts are the compiler options or NULL nlslang is the zoned decimal code page in Globalization Sup
171. eallocated 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 TERMTYPE IN RAW 12 CHAR 1 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 Type of termination to be performed 0 indicates normal completion and 1 indicates abnormal termination which is only requested if there is an error Gateway RPC Interface B 5 Calling Gateway Functions to Execute Transaction Programs PGATCTL PGATCTL is called by the TRACE_LEVEL parameter at ORACLE_HOME dg4appc admin initsid ora file for Microsoft or SORACLE_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 TRFUNC IN CHAR 1 TRFLAGS IN BINARY_ INTEGER For a gateway using SNA Conversation identifier return
172. ecscseeeseececesensnseececesessneseseeases 7 8 Declaring TIP Variables iato anotar little entabla tie 7 8 Initializing the Conversations es seu sai ei eee oe iae e ariaa r E See heana 7 10 Transaction Instance Parameter c ccccccccssscsssecsssecsecsssecssecessecescecsecessseseeeesseseseeceesesseceeeecsees 7 11 Overriding TIP Initialization Sissin ceticis a i 7 11 Security Considerations ici cata era ova iae iit aa paatna adas 7 13 Exchanging Data ii A A A A A A ct 7 13 Terminating the Conversation ccccccccescsesesescscseesesescscsesesesescsesesesescsesssesescsesesnseecsescssseseeceses 7 13 Error Handle aa 7 14 Granting Execute Author nica 7 14 Calling PG4TCPMAP ri aeina aa ranar ra aE liarla trancas oasis dani 7 14 Executing the A pplication comic tii 7 14 Application Development with Multi Byte Character Set Support ees 7 15 Privileges Needed to Use TIPS 0scsncisciccccccicecectiscice ces ct dd bai 7 16 Troubleshooting TIP Definition 6 9 0 0 0 00 A AS IA AAA AA 8 1 Problem Analysis with PG DD Diagnostic References ooonnnicncnnnnnninnnnncncnnncncnnnnononornrornconornrornnnos 8 2 Problem Analysis with PG DD Select SeriptS ooninnnnnnnnnnnnnnnnnnnnnnnnncncncncncororornrnno raro raro rororarorornncns 8 3 Data Conversion ELTOTS Luli A e a eiei e a laste E 8 4 Problem Analysis with TIP Runtime Traces oonooniicionnnnnnnnnnemecnccnnccacerin ca rrcnonon arco cnnnaran cn cnonono 8 5 TIP Runtime Trace Controls
173. ed For CICS this must be the CICS Transaction ID and is 1 to 4 characters in length a For IMS this must be the IMS Transaction Name and is 1 to 8 characters in length For AS 400 this must be specified as library program and cannot exceed 21 bytes Name values can be alphanumeric with and characters only if unquoted Quoted values can contain any character and delimited by quotes or apostrophes Case is preserved for all values This parameter is required for a gateway using TCP IP support for IMS Connect It must be the IMS Transaction Name The IMS Transaction Name must be 1 to 8 characters in length Procedural Gateway Administration Utility 2 11 PGAU Commands Table 2 3 Cont DEFINE TRANSACTION Parameter Descriptions Parameter Description LOGMODE name SYNCLEVEL 0 1 NLS_LANGUAGI El nlsname REMOTE_MBCS nlsname LOCAL_MBCS nlsname This parameter is optional on a gateway using SNA Overrides the LOGMODE within the Side Information Profile if the Side Information Profile was specified It specifies the name of a VTAM logmode table entry to be used to communicate with this transaction and is 1 8 characters in length Name values can be alphanumeric with and characters only Values cannot be quoted Case is not preserved and always translated to upper case This parameter is not applicable whe
174. ed 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 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 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 AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 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 AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows PGATRAC This function is called to write a line of user dat
175. ed might provide additional information Note A runtime switch is also required to execute the warning logic PKGEX DC only causes the warning logic to be included in the TIP Refer to Controlling TIP Runtime Conversion Warnings on page 8 6 in Chapter 8 Troubleshooting Additional messages are written to a named pipe for tracing the data conversion steps performed by the TIP as it executes This option only causes the trace logic to be generated in the TIP It must be enabled when the TIP is initialized Refer to Controlling TIP Runtime Conversion Warnings in Chapter 8 Troubleshooting for more information a DR Dictionary Reference PL SQL single line Comments are included in TIPs which reference the PG DD id numbers for the definitions causing the TIP function calls and conversions Procedural Gateway Administration Utility 2 17 PGAU Commands GROUP Examples Refer to Sample PGAU GENERATE Statement in Appendix F for examples of GENERATE commands GENERATE Usage Notes All PGAU GENERATE trace messages are designated PGU 39nmn Refer to the SORACLE_HOME dg4appc mesg pguus msg file on Microsoft Windows or SORACLE_HOME dg4appc mesg pguus msg on UNIX based systems for further information on any given trace message WE a Thepgau trc trace message output file is overwritten by the next invocation of GENERATE regardless of the TRACE specification A trace header record is always writte
176. ement Table A 1 presents the Oracle sequence objects and their descriptions Table A 1 Oracle Sequence Objects Oracle Sequence Objects Descriptions pga envrseq Environment id tag Database Gateway for APPC Data Dictionary A 1 PG DD Environment Dictionary Table A 1 Cont Oracle Sequence Objects Oracle Sequence Objects Descriptions pga compseq Compiler id tag pga eattrseq Environment Attribute id tag pga dtypeseq Datatype id tag pga dtattseq Datatype Attribute id tag Environment Dictionary Tables The environment dictionary tables contain constants that describe the following components of the operating environment pga_maint pga_environments pga_env_attr pga_env_values pga_compilers pga_datatypes pga_datatype_attr pga_datatype_values pga_usage pga_modes pga_maint The pga_maint table stores the PG DD maintenance information including version number and change history as presented in Table A 2 Table A 2 pga_maint Column Type Contents version number 10 4 PG DD version in format VVRRFF rrff where VV base version RR base release FF base fix rr port specific release Ef port specific fix mntdate date Oracle date and time at which the PG DD was upgraded change varchar2 256 Description of the PG DD upgrade pga_environments The pga_environments table stores the defined environment keywords as presented in Table A
177. en you configured the gateway Preparing the Gateway to Communicate Using TCP IP If your gateway is using TCP IP support for IMS Connect then you must use the pg4tcpmap tool to create the required mapping between PGAINIT parameters and the target system network address information The pg4tcpmap tool maps the Side Profile Name specified in a DEFINE TRANSACTION to TCP IP and IMS Connect attributes such as port number IP address host name and IMS subsystem ID The TCP IP parameters are used to start a conversation with the target transaction program The pg4tcpmap tool must be run in order to populate the PGA_TCP_IMSC table before executing any TIPs which rely on TPC IP support for IMS Connect a Refer to Chapter 6 PG4TCPMAP Commands TCP IP Only in this guide for complete instructions for setting up and executing pg4tcpmap commands to populate the PGA_TCP_IMSC table Chapter 6 also explains the content of the PGA_TCP_IMSC table and an example of how to use the table A trace file from a sample pg4tcpmap execution is located in Chapter 8 Troubleshooting in this guide A screen output file is located in Appendix B Gateway Initialization Parameters for TCP IP Communication Protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database
178. ent Application Development TCP IP Only 7 15 Privileges Needed to Use TIPs Privileges Needed to Use TIPs Execute privileges must be explicitly granted to callers of TIPs or procedures This privilege cannot be granted through a role Any TIP user wanting to trace a TIP must be granted execute privileges on the rtrace and ptrace procedures Refer to the Configuring PGAU chapter appropriate for your communications protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows and the Oracle Database Advanced Application Developer s Guide for more information For example On Microsoft Windows C gt sqlplus pgaadmin pwedatabase_ specification string SQL gt grant execute on pgaadmin purge_trace to tip _user_userid SQL gt grant execute on pgaadmin read_trace to tip _user_userid On UNIX based systems sqlplus pgaadmin pw database_specification_string SQL gt grant execute on pgaadmin purge_trace to tip_user_userid SQL gt grant execute on pgaadmin read_trace to tip_user_userid After a TIP has been developed the TIP user must be granted execute privileges on the TIP by the TIP owner The TIP owner is usually PGAADMIN but can be another user who has been granted either the PEDDDEF or PGDDGEN
179. eps to Communicate Between Gateway and Mainframe Using SNA The following steps describe the Windows to mainframe communications process illustrated in Figure 1 3 Communication Between the Oracle Database and the Mainframe Using SNA when your communication protocol is SNA to communicate between the gateway and the mainframe 1 From SQL Plus execute pgacics This invokes the PL SQL stored procedure in the Oracle database For Microsoft Windows C gt sqlplus lt userid gt lt password gt lt database_specification_string gt SQL gt execute pgacics lt SCIC htiw gnitacinummoc si yawetag ruoy snoitalutargnoC gt For UNIX Based platforms sqlplus lt userid gt lt password gt lt database_specification_string gt SQL gt execute pgacics lt SCIC htiw gnitacinummoc si yawetag ruoy snoitalutargnoC gt 2 The pgacics PL SQL stored procedure will start up the gateway The gateway will start up communication with CICS Transaction Server for z OS through SNA and will call FLIP 3 FLIP processes the input generates the output and sends the output back to the database gateway 4 Finally the database gateway will send the output back to the PL SQL stored procedure in the Oracle database The result is displayed in SQL Plus gt Congratulations your gateway is communicating with CICS lt PL SQL procedure successfully completed Figure 1 3 Communication Between the Oracle Database and the
180. er numval of declared precision and scale into a RAW byte string in the remote host internal format Syntax function NUMBER_TO_RAW_FORMAT numval IN NUMBER n2rfmt IN RAW RETURN RAW Where Table C 12 describes the parameters in this function Table C 12 NUMBER_TO_RAW_FORMAT Function Parameters Parameters Description numval is the Oracle number to be converted C 8 Oracle Database Gateway for APPC User s Guide UTL_PG Functions WMSGCNT Table C 12 Cont NUMBER_TO_RAW_FORMAT Function Parameters Parameters Description n2rf mt isa RAW 2048 format specification returned from MAKE_NUMBER_TO_RAW_FORMAT Defaults None Return Value A RAW value corresponding in value to n Error and Warning Messages If you receive an ORA xxxx error or warning message refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it WMSGCNT tests a wmsgb1k to determine how many warnings if any are present Syntax function WMSGCNT wmsgblk IN RAW RETURN BINARY_INTEGER Where Table C 13 describes the parameter in this function Table C 13 WMSGCNT Function Parameter Parameter Description wmsgblk is the warning message block returned from one of the following functions m MAKE_NUMBER_TO_RAW_FORMAT m MAKE_RAW_TO_NUMBER_FORMAT m NUMBER_TO_RAW m RAW_TO_NUMBER Defaults None Return Value A BINARY_INTEGER value eq
181. errides a warning function has been included in the following UTL_PG functions 8 4 Oracle Database Gateway for APPC User s Guide Problem Analysis with TIP Runtime Traces MAKE _NUMBER_TO_RAW_FORMAT MAKE_RAW_TO_NUMBER_FORMAT NUMBER_TO_RAW RAW_TO_NUMBER Problem Analysis with TIP Runtime Traces TIPs should be generated by the PGAU GENERATE command with the PKGEX DC diagnostic option to include TIP data conversion trace logic in the TIP TIP function call trace logic is always included in every TIP This is runtime trace instrumentation and has some overhead when tracing is enabled but negligible overhead when tracing is disabled Refer to Section GENERATE on page 2 15 in Chapter 2 Procedural Gateway Administration Utility for more information 1 Regenerate TIPs with the PKGEX DC DR options and recompile the TIP body file tipname pkb Avoid recompiling the TIP specification Revise the application that calls the TIP initialization function tipname_init to pass the trace flags parameter with data conversion and function call tracing enabled Refer to Controlling TIP Runtime Data Conversion Tracing on page 8 7 If the problem causes an exception to be raised in the TIP and the application contains an exception handler the application exception handler should be Commented out to prevent it from handling the exception and preventing the exception point of origin from being reported When t
182. es to assist in setting up and administrating Oracle products including procedures scripts commentary and tuning and configuration best practices bulletins Please logon to My Oracle Support before installing or administrating your product to search for up to date information about Oracle Database 11 Release 2 11 2 for Microsoft Windows 32 Bit In addition My Oracle Support offers forums for information sharing among Oracle customers and direct communication with Oracle Support Services My Oracle Support is available to Product Support Customers at no extra cost Sign up for free membership for this service at the following site http metalink oracle com Use your Support Access Code SAC number to register Oracle Products and Other Documentation For U S A customers the Oracle Store is at http store oracle com Links to Stores in other countries are provided from this site Customer Service Oracle Support Services contacts are listed at http www oracle com support Support for Hearing and Speech Impaired Customers Oracle provides dedicated Text Telephone TTY access to Oracle Support Services within the United States of America 24 hours a day seven days a week a For technical questions call 1 800 446 2398 a For non technical questions call 1 800 464 2330 Education and Training Training information and worldwide schedules are available from http education oracle com 1 Introduction t
183. eter It specifies which singular version of a definition is to be removed or if ALL then all definitions are callvers removed for the given definition named The default of the highest numbered version of the named definition is assumed transvers ALL i A if VERSION is omitted Examples Refer to Sample PGAU UNDEFINE Statements in Appendix F for examples of UNDEFINE CALL commands UNDEFINE CALL Usage Notes a Removing definitions only prevents PL SQL packages from being subsequently generated TIPs can still be recreated if the pkh and pkb specification files exist and those previous TIPS can be invoked if they remain in the database of the Oracle database Whether such TIPs execute successfully depends on whether the corresponding remote transaction programs are still active a Remove a CALL definition only after all TRANSACTIONs which reference it are removed No integrity checking is done m a You must place at the end of the command Procedural Gateway Administration Utility 2 29 PGAU Commands UNDEFINE DATA Purpose Use this command to remove an occurrence of the DATA definition in the PG Data Dictionary Syntax UNDEFINE DATA dname VERSion datavers ALL I Parameters Table 2 11 describes the UNDEFINE DATA parameters Table 2 11 UNDEFINE DATA Parameter Descriptions Parameter Description DATA dname A mandatory parameter It specifies the name associated
184. evious UNDEFINE statements leave the DATA definition for EMPNO and the CALL definition for DB2IDIAG in the PGA DD Administration Utility Samples F 7 Sample PGAU UNDEFINE Statements F 8 Oracle Database Gateway for APPC User s Guide A APPC runtime 4 22 SENDs and RECEIVEs TIP CALL correspondence 4 11 trace 8 11 8 12 using with terminal oriented transaction program 4 26 APPC conversation sharing 4 20 concepts 4 21 examples 4 23 for too large TIPs 4 23 overrides and diagnostics 4 25 TIP compatibility 4 22 usage 4 22 architecture commit confirm 5 4 components of the gateway 1 7 ASCII automatic conversion 1 3 C CALL correspondence on gateway using SNA 4 11 on gateway using TCP IP 7 5 call correspondence order restrictions on gateway using SNA 4 13 on gateway using TCP IP 7 7 CICS 1 10 CICS Transaction Server gateway starts communication with 1 11 client application development calling a TIP on gateway using SNA 4 14 on gateway using TCP IP 7 8 customized TIPs for remote host transaction 4 6 declaring TIP variables 4 14 7 8 error handling on gateway using SNA 4 20 on gateway using TCP IP 7 14 examples and samples 1 6 exchanging data 4 19 on gateway using TCP IP 7 13 executing 4 20 7 14 Index granting execute authority 4 20 7 14 on gateway using TCP IP 7 1 overriding TIP initializations 4 17 on gateway using TCP IP 7 11 overview 4
185. eway Administration Utility for more information about the DEFINE TRANSACTION statement These PG DD defined transaction attributes are generated into TIPs as defaults and can be overridden at TIP initialization time This facilitates the use of one TIP which can be used with a test transaction or system and can later be used with a production transaction or system without having to regenerate the TIP The override_Typ record datatype describes the various transaction attributes that can be overridden by the client application The following overrides are currently supported tranname can be set to override the value that was specified by the TPNAME parameter of the DEFINE TRANSACTION statement netaddr can be set to override the value that was specified by the SIDEPROFILE parameter of the DEFINE TRANSACTION statement In addition to the transaction attributes defined in the PG DD there are two security related parameters conversation security user ID and conversation security password that can be overridden at TIP initialization time The values for these parameters normally come from either the database link used to access the gateway or the Oracle database session There are cases when the Oracle database user ID is not sufficient for accessing the OLTP system The user ID and password overrides provide a way to specify those parameters to the OLTP system The following overrides a
186. executed by the HOST command does not change the current directory in the PGAU execution environment mn You do not need to place at the end of the command Procedural Gateway Administration Utility 2 19 PGAU Commands PRINT Purpose Use this command to print the value of a variable defined with the VARIABLE command Syntax The PRINT command has the syntax PRINT varname Parameters varname is a variable name which is defined by a variable command Examples PRINT ename PRINT balance PRINT Usage Notes a You do not need to place at the end of the command REDEFINE DATA Purpose The existing data definition in the PG Data Dictionary is modified PG DD column values for DATA FLD and POS remain the same for redefined data items This permits existing CALL and DATA definitions to utilize the redefined data REDEFINE does not create a different version of a data definition and the version number is not updated Syntax REDEFINE DATA dname VERSion datavers PLSDNAME plsdvar FIELD fname PLSFNAME plsfvar USAGE PASS ASIS SKIP COMPOPTS options REMOTE_LANGUAGE nlsname LOCAL_LANGUAGE n1sname LANGUAGE language lt definition INFILE filespec gt Parameters Table 2 6 describes the REI T O EFINE DATA parameters Table 2 6 REDEFINE DATA Parameter Descriptions Parameter Des
187. f PGA_TCP_IMSC table 6 2 creating a TIP 7 1 determining validity of TIP specification E 2 elements of TIP RTP correspondence 7 4 examples and sample files used in this guide 1 6 function in the gateway 1 1 gateway support for description 1 3 IMS enabled 1 5 mapping parameters using pg4tcpmap tool 7 14 mapping SNA parameters to TCP IP 6 1 non persistent socket transaction type 1 14 OLTP in gateway architecture 1 7 persistent socket transaction type 1 14 PGAU DEFINE TRANSACTION command 3 4 remote host languages supported 3 2 remote transaction initiation 1 9 remote transaction termination 1 9 SENDs and RECEIVEs TIP CALL correspondence 7 5 setting initsid ora parameters 6 5 simple communication between gateway and integrating server 1 14 steps to communication between server and IMS 1 15 steps to writing a TIP 1 17 supports only IMS as OLTP 1 3 1 5 TIP granting privileges needed 7 16 TIP internals E 1 TRANSACTION correspondence 7 7 transaction types 1 14 terminal oriented transactions modifying 4 26 terminating a TIP conversation 4 19 7 13 terms gateway terms defined 1 3 TIP 1 6 4 2 7 2 APPC conversation sharing 4 21 4 22 background references E 1 CALL correspondence 4 11 on gateway using SNA 4 11 on gateway using TCP IP 7 5 order restrictions 4 13 calling from the client application 4 14 7 8 calling and controlling on gateway using SNA 4 1 on gateway using TCP IP 7 1 client applicati
188. f your gateway is using the SNA communication protocol The RHT data exchange steps are identified under the following languages You may use COBOL for CICS IMS a You may use IBM 370 Assembler for CICS IMS a You may use IBM REXX for CICS IMS z OS If your gateway is using the TCP IP communication protocol IMS is the only OLTP that is supported when the gateway is using TCP IP support for IMS Connect The RHT programs must use embedded I O PCB function calls The function is identified only under the COBOL and Assembler languages PGAU DEFINE CALL Command Make a call list of every data exchange This list dictates a series of PGAU DEFINE CALL statements Refer to DEFINE CALL in Chapter 2 Procedural Gateway Administration Utility for more information about this PGAU command The three important parameters that you will use for each call are cname the name of the call definition to be created dname the name of the data structure to be exchanged and whether it is send OUT or receive IN RHT send corresponds to a TIP OUT and RHT receive corresponds to a TIP IN If your communication protocol is SNA Refer to Section Flexible Call Sequence on page 4 12 for more information about PGAU DEFINE CALL commands 3 2 Oracle Database Gateway for APPC User s Guide Evaluating the RHT If your communication protocol is TCP IP Refer to Section Flexible Call Sequence
189. fined to the OLTP system being accessed This database must be recoverable and must be accessible by the OLTP as part of the same unit of work as the OLTP application s databases so that updates to the transaction log database will be kept in sync with updates to the application s databases in a single unit of work The commit confirm transaction log database need contain only the Oracle Global Transaction ID and a date time stamp The Oracle Global Transaction ID is 169 bytes long and must be the key field The date time stamp is used for purging old entries that can be left in the log after certain failure scenarios For simplicity all commit confirm applications under a particular OLTP should share the same commit confirm transaction log OLTP Transaction Logging Code Code must be added to each OLTP transaction invoked by a commit confirm gateway to perform the transaction logging required by the gateway s commit confirm implementation This code must receive the Oracle Global Transaction ID from the gateway and write that information into the OLTP commit confirm transaction log database For maximum flexibility and ease of use this code can be written as a subroutine callable from any commit confirm transaction on your OLTP system This code must be executed at the beginning of each commit confirm transaction prior to the first APPC receive and then immediately after each COMMIT or ROLLBACK in the transaction This ensures that the loggin
190. finitions Messages are written tracing the loading of transaction call data parameter field attribute environment and compiler information from the PG DD a OC Oracle Calls Messages are written tracing the Oracle UPI call results for SQL statement processing and SELECTS from the PG DD TG TIP Generation Messages are written tracing steps completed in TIP Generation typically a record for each call parameter and data field for which a PL SQL code segment has been generated causes additional TIP execution time diagnostic logic to be included within the generated PL SQL package PKGEX suboptions are delimited by commas a DC Data Conversion Enables runtime checking of repeating group limits and the raising of exceptions when such limits are exceeded Enables warning messages to be passed from the UTL_PG data conversion functions m NUMBER_TO_RAW n RAW_TO_NUMBER MAKE_NUMBER_TO_RAW_FORMAT MAKE_RAW_TO_NUMBER_FORMAT The additional logic checks for the existence of warnings and if present causes them to be displayed using DBMS_OUTPUT calls The TIP generation default is to suppress such warnings on the presumption that a TIP has been tested with production data and that data conversion anomalies either do not exist or are known and to be ignored If errors occur which might be due to data conversion problems regeneration of the TIP with PKGEX DC enabl
191. for example parm6 IN and parm7 OUT They could still be exchanged as two parameters on a single TIP call or one parameter each on two TIP calls however Lastly the remote transaction program s remaining three RECEIVE fields are supplied by tip_cal14 parameters 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 Call Correspondence Order Restrictions Each TIP public function first sends all IN parameters before it receives any OUT parameters Thus a remote transaction program expecting to send one field and then receive one field must correspond to separate TIP calls For example tip_callO parmO OUT lt APPC SEND outfield from remote TP PGAXFER RPC checks first for parameters to send but finds none and proceeds to receive parameters tip_callI parmI IN gt APPC RECEIVE infield to remote TP PGAXFER RPC processes parameters to send and then checks for parameters to receive but finds none and completes therefore a single TIP public function 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
192. ftware or commercial technical data pursuant to the applicable Federal Acquisition Regulation and agency specific supplemental regulations As such the use duplication disclosure modification and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract and to the extent applicable by the terms of the Government contract the additional rights set forth in FAR 52 227 19 Commercial Computer Software License December 2007 Oracle USA Inc 500 Oracle Parkway Redwood City CA 94065 This software is developed for general use in a variety of information management applications It is not developed or intended for use in any inherently dangerous applications including applications which may create a risk of personal injury If you use this software in dangerous applications then you shall be responsible to take all appropriate fail safe backup redundancy and other measures to ensure the safe use of this software Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications Oracle is a registered trademark of Oracle Corporation and or its affiliates Other names may be trademarks of their respective owners This software and documentation may provide access to or information on content products and services from third parties Oracle Corporation and its affiliates are not responsible for and expressly disclaim a
193. g is done at the beginning of each unit of work OLTP Forget Recovery Transaction A separate APPC transaction must be created on the OLTP system that can be started by the gateway to forget a transaction once it has been successfully committed and to query a transaction s state during recovery processing This transaction deletes the entry for a particular Oracle Global Transaction ID from the OLTP commit confirm transaction log database during forget processing and Implementing Commit Confirm SNA Only 5 3 Application Design Requirements queries the entry for a particular Oracle Global Transaction ID from the OLTP commit confirm transaction log database during recovery processing Note Make sure that the gateway initialization parameters and the OLTP parameters are properly configured as described in Chapter 11 of the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Chapter 8 of the Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows depending on your platform Application Design Requirements When designing commit confirm applications for use with the Oracle Database Gateway for APPC there are some requirements you must meet to provide the ability for the gateway to determine the state of a transaction in the event of a failure If the
194. hapter 2 Procedural Gateway Administration Utility and Sample PGAU DEFINE TRANSACTION Statement on page F 2 in Appendix F Administration Utility Samples In this example the following DEFINE TRANSACTION statement is used to match this information with the inserted row in the PGA_TCP_IMSC table DEFINE TRANSACTION IMSFLIP CALL FLIPMAIN SIDEPROFILE PGATCP TPNAME FLIP NLS_LANGUAGE american_america us7ascii Calling the TIP from the Client Application Once a TIP is created a client application must be written to interface with the TIP A client application that calls the TIP functions must include five logical sections a declaring TIP variables a initializing the conversation a exchanging data terminating the conversation a error handling Declaring TIP Variables The user declarations section of the tipname doc file documents the required declarations When passing PL SQL parameters on calls to TIP functions the client application must use the exact same PL SQL datatypes for TIP function arguments as are defined by the TIP in its specification section Assume for example the following is in the TIP specification or tipname doc FUNCTION tip _call1 tranuse IN BINARY_INTEGER tip_varl lo_mode pls _typel tip record io_mode tran_rectype 7 8 Oracle Database Gateway for APPC User s Guide Calling the TIP from the Client Application RETURN INTEGER TYPE tran
195. he TIP exception is next raised its source line number in the TIP is reported Record this information Execute the application with diagnostic TIP initialization If the TIP trace pipe inlet overflows due to the application calls causing the TIP to write trace messages in the TIP trace pipe inlet you have one minute from the start of the overflow condition to begin Step 4 and empty the TIP trace pipe Otherwise exception ORA 20703 PGA TIP pipe send error is issued ending the diagnostic session possibly before any relevant trace information is generated Retrieve and record the TIP trace message stream Use SQL Plus to connect to the same Oracle user ID executing the application or the user ID under which the TIP is executed This establishes a second session from which the trace pipe outlet can be read preventing the TIP trace pipe from overflowing at the TIP trace pipe inlet a Issue the command set serveroutput on size nnnnn b Issue the command to record the trace output spool tipname trc c Issue the command to retrieve the trace stream exec rtrace tipname If the application is long running repeat this command as often as needed until all trace messages have been retrieved If any exceptions are raised note their prefix number and full message text Troubleshooting 8 5 TIP Runtime Trace Controls 6 Analyze the TIP trace message stream A normal trace is shown for the pgadb2i TIP in
196. he client application and data parameters exchanged must have been declared as variables by the client application The TIPs provide both the required datatype definitions and the RHT function calls for the client application Refer to the TIP content documentation file for each specific TIP RHT for the exact syntax of the TIP function calls and definitions of the parameter datatypes exchanged Terminate each initialized RHT using the TIP termination function To terminate an RHT its corresponding TIP termination function must be called to terminate the RHT and its conversation and to initiate TIP cleanup The RHT to be Client Application Development SNA Only 4 9 Ensuring TIP and Remote Transaction Program Correspondence terminated is specified by its TIP schema name the same schema as for its data exchange function calls and the tranuse value when multiple instances of the same RHT are being terminated RHTs and their corresponding TIPs can be terminated in any sequence desired by the client application and do not have to be terminated in the same order in which they are initialized Note The specific syntax of the various TIP data exchange variables function calls is the same as was previously defined in the PG DD for the particular RHT and can be researched by examining the TIP content documentation file tipname doc or the TIP specification file produced when the TIP was generated If a TIP has not ye
197. he same transaction name and version 8 2 Oracle Database Gateway for APPC User s Guide Problem A nalysis with PG DD Select Scripts REPORT selects definitions from the PG DD and produces a listing showing the DATA CALL and TRANSACTION definitions and the ID user supplied definition program and identify all corresponding exchanges and transmitted 4 Look for and investigate any mismatches such as a different numbers of send receive calls a different sequence of send receive calls a different parameter lists on send receive calls number of each Compare the reported definitions with those used in the remote transaction the data formats a different data fields within each exchanged parameter a different lengths for each exchanged parameter unsupported datatypes for each exchanged parameter a improperly initialized control fields for repeating group counts BMVSCOBOLII affected clauses include OCCURS n TIMES DEPENDING ON field remapped group criteria BMVSCOBOLTII affected clauses include REDEFINES fieldl WHEN field2 criteria Problem Analysis with PG DD Select Scripts PGAU GENERATE error messages and TRACE OC entries reference SOL SELECT statements Refer to Table 8 2 for the meaning of the name designations for each entry Table 8 2 Meaning of TRACE OC Output Name Entry SED Select Environment Da
198. here Table 2 1 describes the parameters in this syntax Table 2 1 DEFINE CALL Parameter Descriptions Parameter Definition CALL cname is a mandatory parameter It is the name of the call definition to be created PKGCALL pcname is an optional parameter It specifies the name of the PL SQL package procedure or function by which the application might invoke the call The default value cname is assumed if this operand is omitted in which case cname must also be valid in PL SQL syntax and unique within the transactions and TIPs referencing this call PARMS dname is an optional parameter It specifies a list of previously defined data input to and output from this PL SQL function call and the VERSION datavers type ofeach parameter input to the call output from or both The order in which the parameters are specified determines the order in which they must appear in subsequent calls to the TIP from an application IN OUT IN OUT Each dname specifies a previously defined data item and is mandatory IN OUT IN OUT specifies the PL SQL call mode of the parameter and indicates whether the dname data is sent received or both in the exchange with the remote transaction program One must be chosen VERS datavers is an optional specific version number of the dname data definition if not the latest If this operand is omitted it is assumed that the call takes no parameters Examples
199. i conversational One Shot Transactions A simple remote transaction program which receives one employee number and returns the employee record could have a TIP which provides one call passing the employee number as an IN parameter and returning the employee record as an OUT parameter An additional two function calls must be provided by this and every TIP aremote transaction program init function call aremote transaction program terminate function call The most simple TIP has three public functions such as tip_init tip_main and tip_term The client application calls tip_init tip_main and tip_term in succession The corresponding activity at the remote site is remote transaction program start data exchange and remote transaction program end 4 4 Oracle Database Gateway for APPC User s Guide Understanding the Remote Host Transaction Requirements The remote transaction program might even terminate itself before receiving a terminate signal from the gateway This sequence is usual and is handled normally by gateway logic This kind of remote transaction program is termed one shot Persistent Transactions A more complex remote transaction program has two modes of behavior an INQUIRY or reporting mode and an UPDATE mode These modes can have two TIP data transfer function calls one for INQUIRY and one for UPDATE Such a TIP might have five public functions For example a tip i
200. ient application depending on PGADB21 DB2IFORM PROCEDURE 2nd client application depending on PGADB21 DB2IDRIV PROCEDURE 3rd client application depending on PGADB21 PGADB2I PACKAGE BODY a recompilation of the body El E E Note that the recompilation of the body does not invalidate its dependent object the specification or the client application indirectly If your gateway is using the TCP IP communication protocol issue the following fro SQL Plus SQL gt column ddl_date format A22 heading LAST_DDL SQL gt 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 PGTFLIP PACKAGE APR 24 03 03 04 58 VALID PGTFLIP PACKAGE BODY APR 24 03 03 04 02 VALID PGTFLIPD PROCEDURE APR 24 03 03 04 09 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 72 PGTFLIP PACKAGE the specification PGTFLIPD PROCEDURE client application depending on PGADB2T PGTFLIP PACKAGE BODY a recompilation of the body bh Note that the recompilation of the body does not invalidate its dependent object the specification or the client application indirectly Dependent TIP Body or Specification Changes You can also change the data structures or
201. ies 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 PEAINIT_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 MOI PROFNAME is set to blanks or a null value the LUNAME TPNAME and MODENAME parameters are all required to be non blank values If values an exception is generated However if PROFNAM I DENAME If they are not all set to non blank E 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 TPNAMI E or MOI DENAME
202. ified the same tpname RHTA the same remote host transaction is always called for initialization APPC Conversation Sharing Overrides and Diagnostics TIP default override parameters are processed in the TIP init function which was called to perform initialization Once the APPC conversation is established no further sharing of overriding parameters is necessary You need do nothing more than pass the overrides to the TIP init function TIP diagnostic parameters are shared among all TIPs sharing a given conversation In effect requesting diagnostics of the TIP performing initialization causes the same diagnostics to be requested of all TIPs sharing the conversation Requesting diagnostics from only one TIP of several sharing a conversation is not possible The application designer or user need only pass the TIP runtime trace controls to the TIP init function Application Development with Multi Byte Character Set Support COBOL presently only supports double byte character sets DBCS for PIC G datatypes PGAU processes COBOLII PIC G datatypes as PL SQL VARCHAR2 variables and generates TIPs which automatically convert the data according to the Oracle NLS_LANGUAGEs specified for the remote host data and the local Oracle data These Oracle NLS_LANGUAGEs can be specified as defaults for all PIC G data exchanged by the TIP with the remote transaction see DEFINE TRANSACTION REMOTE_MBCS or LOCAL_MBCS The Oracle NLS_LANGU
203. il a a A a E rra aa a r aa itt 2 23 REPORT A ee S TEA 2 24 O EEEN 2 26 SHOW esos A San Ma ee ee TEE are ee 2 27 SPOO Live asecdive a tees Site oe eee hs Se eee eee Sn eS aen Si 2 28 WNDEFINE CAT aia 2 29 UNDEFINE DA TA A A AAA A ae ie LE es 2 30 UNDEFINE TRANSACTION aoi rei raa a a E cas 2 30 VARIABLE 0 ea a a es ele ile erie I nah 2 31 Creating a TIP Granting Privileges for TIP Creators ccccccscsssscscesesssestssneseseeceseseseecenesesesesnenssesesceeesesssnaanenees 3 1 Evaluating the RAT soii dad ado 3 2 Identify the Remote Host Transaction ooonconicncnnnnnnnnoninnonononnnonononononnnonono ran no ninno ran nn ninio ro ran cn craran arcos 3 2 PGAU DEFINE CALL Command Ai 3 2 PGAU DEFINE DATA Command aspiren eaa maraa aeaaea aiae aaia aa ea aaa a aeaa 3 3 PGAU DEFINE TRANSACTION Command on a Gateway Using SNA cece 3 3 PGAU DEFINE TRANSACTION Command on a Gateway Using TCP TP ooonicinininccconnnonones 3 4 Writing the PGAU Statements inicial laicas 3 4 Writinga PGAU SeriptHile ius italia adi 3 5 Defining and Generating the TIP iiion idana pinataas onononcnanonononenos 3 6 Compiling the TIP o A ds S aaae eae aes 3 7 TIP Content Documentation tipname dOC ocicnicicicnnonnnnincononinnononcanonincnnnnnono ron coninnonan coco ncononanananonono 3 8 Client Application Development SNA Only Overview of Client Application oonocinnnnnnnnnnninonicnnnnnnnnoncncnnonanocnroroconononorn keasrian de isei ron itore ranas 4 1
204. ine the data which is to be exchanged with remote transaction programs It generates the PL SQL Transaction Interface Packages TIPs discussed in Chapter 3 Creating a TIP Appendix E Tip Internals and depending upon your communication protocol either Chapter 4 Client Application Development SNA Only or Chapter 7 Client Application Development TCP IP Only This chapter contains the following sections Overview of PGAU on page 2 1 a COMMIT ROLLBACK Processing on page 2 2 a Invoking PGAU on page 2 3 a Definitions and Generation in PGAU on page 2 3 a Process to Define and Test a TIP on page 2 4 PGAU Commands on page 2 6 Overview of PGAU Note If you have existing TIPs that were generated previously on a gateway using the SNA protocol and you want to utilize the new TCP IP feature then the TIPs will have to be regenerated by PGAU with mandatory NLS_LANGUAGE and Side Profile Settings Specify the appropriate ASCII character set in the DEFINE TRANSACTION command This is due to the fact that the gateway assumes that the appropriate user exit in IMS Connect is being used which would translate between the appropriate ASCII and EBCDIC character sets PGAU maintains a data dictionary PG DD which is a collection of tables in an Oracle database These tables hold the definitions of the remote transaction data and how that data is to be exchanged with the remote transaction pr
205. ing TIP Warnings and Tracing on page 8 7 Problem Analysis of Data Conversion and Truncation Errors on page 8 8 Gateway Server Tracing on page 8 10 TIP Definition Errors TIP definition errors occur when a TRANSACTION CALL or DATA entry in the PG DD is not properly defined Use the REPORT with DEBUG statement to list the PG DD contents and GENERATE DIAGNOSE PKGEX DR option to include corresponding ID numbers in the TIP Table 8 1 shows the mnemonic used to represent ID numbers and their correspondence with the following PGAU REPORT with debug listings GENERATE traces and TIPs a PG DD tables and columns from which ID numbers are selected a Oracle sequence objects from which ID numbers originate Troubleshooting 8 1 Problem Analysis with PG DD Diagnostic References Table 8 1 PG DD ID Numbers in Correspondence PGAU REPORT TIP PDGG table col Sequence Object vit transaction pga_trans version pga transvers version v call version pga_call version pga callvers v data version pga_data version pga datavers t transaction id pga_trans trans pga transeg c call id pga_call call pga callseg pga_call_parm call1 d data id pga_call_parm data pga dataseg pga_data data t pga_fields data f field id pga_fields fld pga fieldseq q qualifier id pga_data_values qual pga fieldseg af trans attribute pga_trans_values attr pga tattrseq iat pga_tran
206. inted Data reports are formatted according to their original compiler language and preceded by a PGAU DEFINE DATA command which defines the data to the PG DD CALL and TRANSACTION reports are formatted as PGAU DEFINE CALL or TRANSACTION commands also called statements which effectively define the entry to the PG DD The following command reports the single most recent data definition specified by data name dname or optionally for those specific versions given REPORT DATA dname REPORT DATA dname VERSION version 1 version 2 This command reports all data definitions specified by data name dname REPORT ALL DATA dname The following command reports the single most recent call definitions specified by call name cname or optionally for those specific versions given REPORT CALL cname REPORT CALL cname VERSION version 1 version 2 WITH DATA This command reports all call definitions specified by call name cname REPORT ALL CALLS cname WITH DATA This command reports all call definitions in the PG DD REPORT ALL CALLS WITH DATA When WITH DATA is specified all the data definitions associated with each selected call are also reported The data definitions precede each corresponding selected call in the report output The following command reports the single most recent transaction definitions specified by transaction name tname or optionally for those specific versions given
207. is achieved a small front end remote transaction program can be written to interface between the gateway calls and the transaction application logic For example in CICS the CICS LINK is used to implement this technique a You can modify your existing program so that APPC calls are embedded In the example PGADB2 1 we use CICS and its associated mapped APPC verbs as follows EXEC CICS ASSIGN accepts the conversation initiated by the gateway EXEC CICS RECEIVE receives the arguments EXEC CICS SEND ends the results EXEC CICS RETURN terminates the conversation 4 26 Oracle Database Gateway for APPC User s Guide Privileges Needed to Use TIPs If you do not want to modify your terminal oriented transaction you can insert an APPC capable interface such as IBM Corporation s FEPI for CICS Transaction Server for z OS between the terminal oriented program and the gateway a With IMS TM existing unmodified IMS transactions can be accessed with the gateway using the implicit APPC facility With implicit APPC the standard DLI GU GN and ISRT calls using the I O PCB are automatically converted to appropriate APPC send or receive calls when the IMS transaction is invoked through APPC Privileges Needed to Use TIPs Execute privileges must be explicitly granted to callers of TIPs or procedures This privilege cannot be granted through a role Any TIP user wanting to trace a TIP must be granted execute
208. ize 30 PGAU gt show CHARWIDTH Charwidth 80 PGAU gt show all Instance local Spool OFF Timing OFF Termout ON Echo OFF Stoponerror OFF Maxdata 20480 Arraysize 20 Fetchrows 100 Numwidth 10 Charwidth 80 Longwidth 80 Datewidth 9 ServerOutput OFF SHOW Usage Notes a You do not need to place at the end of the command Purpose Use this command to specify a filename that captures PGAU output All output is directed to the terminal unless TERMOUT is off Syntax The SPOOL command has the syntax SPOOL filename OFF 2 28 Oracle Database Gateway for APPC User s Guide PGAU Commands Parameters If a simple filename is specified with no periods then log is appended to the filename filename is where the output of your executed commands is placed Examples SPOOL log outfile SPOOL out SPOOL OFF SPOOL Usage Notes You do not need to place at the end of the command UNDEFINE CALL Purpose Use this command to remove an occurrence of the CALL definition from PG DD Syntax UNDEFINE CALL cname VERSion callvers ALL J Parameters Table 2 10 describes the UNDEFINE CALL parameters Table 2 10 UNDEFINE CALL Parameter Descriptions Parameter Description CALL cname A mandatory parameter It specifies the name associated with the item to be dropped if no version is specified only the latest highest numbered version is removed VERSion datavers An optional param
209. k options value For example USAGE COMP 4 DISPLAY NULL Max length gt arbitrarily chosen pga_data_attr The pga_data_attr table defines all possible data attribute names allowed by PGA and relates each attribute name to a number and type by which the value of this attribute for a specific data item can be selected from pga_data_values The pga_data_attr table is also used for integrity checks of data attributes when new data items are defined There is one entry in the pga_data_attr table for every possible attribute name to which any PGA supported data item might relate Table A 21 presents the column type and content information for pga_data_attr Database Gateway for APPC Data Dictionary A 13 PG DD Active Dictionary Table A 21 pga_data_atir Column Type Content name varchar2 16 Character string name of attribute Primary key Contains LEVEL RENAMEMF renames member first RENAMEML renames member last REMAPSMF redefines member first REMAPSML redefines member last REMAPSWM redefines when member REMAPSWC redefines when char value REMAPSWN redefines when num value REPGRPFF occurs n REPGRPVF odo first n REPGRPVL odo last n REPGRPVM odo depending member REPGRPKA either Key Asc name REPGRPKD either Key Desc name REPGRPIX either index name PLSTYPE JUST justified char data SYNC aligned aggregate dat
210. kb This generated TIP includes at least three function calls that map to the remote transaction program pgtflip_init initializes the conversation with the remote transaction program pgtflip_main exchanges application data with the remote transaction program pgtflip_term terminates the conversation with the remote transaction program Refer to Appendix E Tip Internals for more information about TIPs if you are writing your own TIP or debugging 5 a client application that calls the TIP The client application calls the three TIP functions with input and output arguments In the example the client application passes an input and the remote transaction and the remote transaction sends back the flipped input as an output Table 7 1 demonstrates the logic flow between the PL SQL driver the TIP and the gateway using the example IMS Connect IMS transaction Table 7 1 Logic Flow of IMS Connect IMS Example Procedures Established Between the Client Gateway and the Remote Transaction Application Oracle TIP mainframe IMS calls tip_init Calls PGAINIT Gateway issues TCP IP socket and connect to initiate the conversation with IMS Connect calls tip_main Calls PGAXFER to send the Gateway issues TCP IP send to IMS input and receive the Connect IMS Connect through OTMA output and XCF talks to the IMS instance IMS RECEIVE completes IMS performs application logic and issues SEND back to gateway The
211. ks to the gateway system The copybooks are later used to define the data items The sample copybook used in the example is documented in Appendix E Administration Utility Samples PGAU DEFINE TRANSACTION Command on a Gateway Using SNA Determine the network address information for the RHT program Your network or OLTP system programmer can provide you with this information The five important parameters that you will use for PGAU DEFINE TRANSACTION are a Side Profile name m TP name a LU name a LOGMODE m SYNCLEVEL You must also identify the Globalization Support character set charset for the language in which the OLTP expects the data At this point if your gateway is using SNA then proceed to Section Writing the PGAU Statements Creating a TIP 3 3 Evaluating the RHT PGAU DEFINE TRANSACTION Command on a Gateway Using TCP IP Before you use this command you will need to know the IMS Connect hostname or TCP IP address port number and the other IMS Connect parameters that are defined as columns within the PGA_TCP_IMSC table Refer to Chapter 6 PG4TCPMAP Commands TCP IP Only for complete information about preparation for mapping parameters to TCP IP using the pg4tcpmap tool When you run the pg4tcpmap tool you need to specify a unique name Side Profile Name That name must be the same name that you are using here to create your TTP If you are converting your gateway from the SN
212. lank character on the line and the COBOL data definition must start on a new line following the standard COBOL rules for column usage and continuations The closing parenthesis and terminating semicolon must be on a separate line following the last line of the COBOL data definition If in COBOL the specification is a COBOL data item or structure defined according to the rules for COBOL Margins are assumed to be standard explicit or implicit continuation is supported Datanames containing invalid characters for example for PL SQL use are translated to their closest equivalent and truncated as required is mutually exclusive with the definition parameter It indicates that the definition is to be read from the operating system file described by filespec instead of an inline definition described by definition Note that i1espec must be enclosed in double quotes Examples Refer to Sample PGAU REDEFINE DATA Statements in Appendix F for examples of REDEFINE commands REDEFINE DATA Usage Notes a Specification of either PLSDNAME FIELD or PLSFNAME allows redefinition of a single data item s names while the definition parameter redefines the named data item s content The presence of FIELD denotes only a single data field single PG DD row uniquely identified by dname fname and version is updated The absence of FIELD denotes that multiple data fields multiple PG DD ro
213. lared above when you declared the RHT TIP datatypes to be exchanged Refer to Appendix D Datatype Conversions for details about how TIPs convert the various types and formats of remote host data Terminate the RHT using the TIP termination function Regardless of the type of RHT being accessed the TIP terminate function should be called to clean up and terminate the conversation with the RHT Conversations with one shot RHTs can be terminated from the gateway server before the RHT terminates The TIP must perform its cleanup as well Cleanup is only performed at the termination request of the client application The client application can request a normal or an aborted termination Refer to Terminating the Conversation on page 4 19 for more information Client Application Development SNA Only 4 7 Client Application Requirements Persistent remote host transaction client applications must a Declare RHT TIP datatypes to be exchanged All client applications must declare variables to be exchanged with the RHTs using TIPs PL SQL datatypes for such variables have already been defined in the TIP corresponding to each RHT the client application need only reference the TIP datatype in its declaration Refer to Declaring TIP Variables on page 4 14 for more information Refer also to the TIP content documentation file for the specific TIP RHT for more information about the exact usage of these variables a Initialize the RHT u
214. le Database Gateway for APPC User s Guide Understanding the Remote Host Transaction Requirements The following sections provide an overview of remote host transaction behavior how this behavior is controlled by the client application and how TIP function calls and data declarations support the client application to control the remote host transaction These sections also provide background information about what the TIP does for the client application and how the TIP calls exchange data with the remote host transaction Preparing the Client Application To prepare the client application for execution you must understand the remote host transaction requirements and then perform these steps 1 Move relevant COBOL records layout copybooks to the gateway system for input to PGAU 2 Describe the remote host transaction data and calls to the PG Data Dictionary PG DD with DEFINE DATA DEFINE CALL and DEFINE TRANSACTION statements 3 Generate the TIP in the Oracle database using GENERATE 4 Create the client application that calls the TIP public functions 5 Grant privileges on the newly created package Understanding the Remote Host Transaction Requirements Browse through the remote host transaction program RTP to determine the PL SQL parameters required on the various client application to TIP calls the order in which the calls are made Identify the remote host transaction p
215. le future reactivation Primary key Set from an Oracle sequence object for call version inserted into PG DD call number 9 0 Call id number Foreign key pga_trans_calls call pga_call_ parm call Set from an Oracle sequence object for each call inserted into the PG DD pga_call_parm The pga_call_parm table relates all parameters of any single transaction call to the data definitions describing each parameter One entry exists in the pga_cal1l_parm table for each parameter on a call in the PARMS operand of the PGAU 1 DEF NE CALL statement One row per parameter duplicates allowed when multiple calls in the pga_cal11 table refer to the same parameters Table A 18 presents the column Table A 18 pga_call_parm type and content information for pga_call_parm Column Type Content call number 9 0 Call number for the referencing call from pga_calls Primary key Set from an Oracle sequence object for each call inserted into the PG DD parm number 9 0 Position in the PARMS argument of DEFINE CALL operation 1 2 3 Primary key cmode varchar2 6 Call mode of this parameter one of the values in pga_data_modes For example IN OUT IN OUT Max length gt IN OUT string length A 10 Oracle Database Gateway for APPC User s Guide PG DD Active Dictionary Table A 18 Cont pga_call_parm Column Type Content
216. lizing the conversation 4 16 7 10 internals E 1 override parameters 4 25 overriding default attributes 4 18 7 12 overview 1 12 1 17 privileges needed 3 1 4 27 public functions tip_init 4 5 tip_ingr 4 5 tip_mode 4 5 tip_term 4 5 tip_updt 4 5 recompiling E 2 E 3 remote transaction correspondence 4 10 remote transaction correspondence on gateway using TCP IP 7 4 remote transaction initiation PGAINIT 1 9 requirements for corresponding with RHT on gateway using SNA 4 10 on gateway using TCP IP 7 4 requirements of the client application 4 6 service 4 21 specification file 3 6 on gateway using SNA 1 13 on gateway using TCP IP 1 18 specifications generated by PGAU 1 8 steps to writing on gateway using SNA 1 12 on gateway using TCP IP 1 17 terminating the conversation 4 19 7 13 trace controls 8 6 tracing 8 8 TRANSACTION correspondence 4 13 7 7 on gateway using SNA 4 13 using transaction instance parameter on gateway using TCP IP 7 11 writing on gateway using SNA 1 12 on gateway using TCP IP 3 4 TIP control file commands 1 12 1 13 1 18 Index 9 on gateway using TCP IP 1 17 TIP specification 4 2 E 2 changes E 3 errors E 4 TIP warnings and tracing suppressing 8 7 tipname doc file 3 8 4 10 4 14 7 8 tipname pkb file 8 5 tname ctl file 3 5 3 6 TP_NAME 5 8 trace option 8 1 TIP definition errors 8 1 TRACE_LEVEL 8 11 traces 8 6 8 7 diagnostic 8 8 e
217. ll warranties of any kind with respect to third party content products and services Oracle Corporation and its affiliates will not be responsible for any loss costs or damages incurred due to your access to or use of third party content products or services Contents PERA E AREA xi Intended AAC A Rda xi Documentation Accessibility ssepe leven tives pues paa a ena ia oia ici xi Related Documents oia ia id da rola ne xii AAA A Sos eee ae Se A xii CONVENTIONS celica idea Ei a iia tasas xii Accessing Installed Documentation occcncccnconnnonicnnanonanincncnononcnronononanorononononann ron cin ie rnn ciao ro ran cn crn ran nn nano xiii Oracle Services and UP dara dee a o aa ia tias xiii 1 Introduction to Oracle Database Gateway for APPC Overview of the Gateway osia eitie oe as eiae ae a ena A iaa tias 1 1 Features OL the Gateway oi RA da cta dit di aa tae td 1 2 EE 1 3 Examples and Sample Files for the GateWay c oooocicicinononncnnnmmmcmnanecacarincenaconon arco crononancncnonono 1 6 Architecture of the Gateway cinc tac 1 7 Communication with the GateWay oooicinocinicinnnnnnonconncnncncanocinnocnnnonan cn nnanano nan cnnnnnanan anno nrcnananananonons 1 8 RPC Functions nasrne A LAA A NE AAA AAA RI ee 1 8 A A E A E A A OCA 1 9 Remote Transaction Initiation oonconnncnnnnnnnnnnnnnnnnannnncnnononnnnnnnononncnonnoncnn cn nononnonononnano nn arc nncn ninos 1 9 Data Exch are iio trineo dota oni becca suck Susu ains Ti Aa
218. losing parenthesis The opening parenthesis must be the last non blank character on the line and the COBOL data definition must start on a new line following the standard COBOL rules for column usage and continuations The closing parenthesis and terminating semicolon must be on a separate line following the last line of the COBOL data definition In COBOL the specification is a COBOL data item or structure defined in accordance with COBOL Margins are assumed to be standard and explicit or implicit continuation is supported Datanames containing invalid characters for example for PL SQL use are translated to their closest equivalent and truncated as required INFILE filespec is mutually exclusive with the definition parameter It indicates that the definition is to be read from the user disk file described by filespec instead of an inline definition described by definition Note that i1espec must be enclosed in double quotes Examples Refer to Sample PGAU DEFINE DATA Statements in Appendix F for examples of DEFI NE DATA commands DEFINE DATA Usage Notes Version of the DATA definition is not specified and defaults to NEXTVAL of the Oracle Sequence Object for DATA PLSDNAME USAGE and LANGUAGE can be specified in any order INFILE filespec is a platform specific designation of a disk file COMPOPTS TRUNC BIN should be used only when the remote host
219. mn type and content information for pga_trans_attr Database Gateway for APPC Data Dictionary A 7 PG DD Active Dictionary Table A 14 pga_trans_attr Column Type Content name varchar2 16 Character string name of attribute Primary key Contains ENVIRONMENT UNAME TPNAME LOGMODE SIDEPROFILE SYNCLEVEL NLS_LANGUAGE REMOTE_MBCS LOCAL _MBCS attr number 9 0 Attribute id assigned Foreign key pga_data_values attr Set from an Oracle sequence object for each supported transaction attribute inserted into the PG DD coltype varchar2 4 Type of Oracle column from which attribute value is retrieved from pga_tran_values For example NUM gt pga_tran_values numval CHAR gt pga_tran_values charval DATE gt pga_tran_values dateval required char 1 If not null required keyword for DEFINE TRANSACTION if null optional pga_trans_values The pga_trans_values table describes the values of transaction attributes A row exists to specify the value of each attribute of each transaction defined in the data dictionary The column type and content information for pga_trans_values is presented in Table A 15 Table A 15 pga_trans_values Column Type Content trans number 9 0 Transaction id from pga_trans trans Primary key Set f
220. must choose which function calls to remove from the former TIP and define into new TIPs Specifically you must decide which PGAU DEFINE CALL statements and their related DEFINE DATA statements should be moved from the old PGAU control file ct 1 into one or more new PGAU control files In addition you must decide which PGAU DEFINE TRANSACTION statements should be included in each new PGAU control file defining each new TIP You must consider several PGAU statements refer to Table 44 for a list of the PGAU statements and their descriptions Table 4 4 PGAU Statements Statement Description DEFINE DATA statements Must be unique They can be shared by all affected PGAU control files provided they are defined to the Procedural Gateway Data Dictionary PG DD before being referenced by DEFINE CALL statements No changes are needed to these statements DEFINE CALL statements Must be unique They need only be referenced by the new DEFINE TRANSACTION statement of the TIP in which they are included provided they are defined to the PG DD before being referenced by a DEFINE TRANSACTION statement The DEFINE CALL statements can optionally be moved to the new PGAU control file of the TIP in which they are included DEFINE TRANSACTION Specified for each new TIP desired and will reference those call statements definitions moved from the former large TIP to the new small TIPs
221. n PL SQL and the gateway the data can end up in the wrong format This appendix contains the following sections a UTL_PG Functions on page C 1 a NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values on page C 11 Note The IBM VS COBOL II compiler has been desupported However the string IBMVSCOBOLI1I is still used as the value of the compiler name parameter to represent any COBOL compiler you choose to use The value IBMVSCOBOLIT should still be used and does not create a dependency on any specific version of the compiler UTL_PG Functions The UTL_PG package is an extension to PL SQL that provides a full set of functions for converting COBOL number formats into Oracle numbers and Oracle numbers into COBOL number formats UTL_PG conversion format RAWs are not portable in this release Additionally generation of conversion format RAWs on one system and transfer to another system is not supported The functions listed in this section are called in the standard PL SQL manner package_name function_name arguments Specifically for UTL_PG routines this is UTL_PG function_name arguments For each function listed below the function name arguments and their datatypes and the return value datatype are provided Unless otherwise specified the parameters are IN not OUT parameters The UTL_PG Interface C 1 UTL_PG Functions Common Parameters The following UTL_PG function
222. n name and parameter list specified in the PGAU DEFINE CALL statement The client application might also declare by reference private variables of the same datatype as the TIP public data parameters to facilitate data passing and handling within the client application thus sharing the declarations created by PGAU GENERATE In this example the following PGAU DEFINE CALL statement must be issued to define the TIP public function DEFINE CALL FLIPMAIN PKGCALL pgtflip_main PARMS FLIPIN IN FLIPOUT OUT Flexible Call Sequence 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 TCP IP SEND 5 fields field1 field5 TCP IP RECEIVE 1 fields field6 TCP IP SEND 1 field field7 TCP IP RECEIVE 3 fields field8 fieldi10 The resulting TIP application call sequence could be tip_calll parm1 OUT lt TCP IP SEND fieldl from remote TP parm2 OUT lt TCP IP SEND field2 from remote TP parm3 OUT lt TCP IP SEND field3 from remote TP tip_call2 parm4 OUT lt TCP IP SEND field4 from remote TP parm5 OUT lt TCP IP SEND field5 from remote TP tip_call3 parm6 IN OUT gt TCP IP RECEIVE field6 in remote TP lt TCP IP SEND field7 from remote TP tip
223. n of DB21 because the DB21 TRANSACTION was defined previously The essential difference of the new version of the DB2I transaction is that the first call uses a new PL SQL record format NEWEMP which corresponds to the COBOL NEWEMP format to query the employee data Caution Record format changes like that discussed above must be synchronized with the requirements of the remote transaction program Changes to the PGA TIP alone result in errors A new remote transaction program with the corequisite changes could be running on a separate CICS system and started through the change from CICSPROD to CICSTEST in the SIDEPROFILE parameter below DEFINE TRANSACTION DB2I CALL DB2IMAIN VERSION ccccc DB2IDIAG SIDEPROFILE CICSTEST TPNAME DB21 LOGMODE ORAPLU62 SYNCLEVEL 0 NLS_LANGUAGE AMERICAN_AMERICA WE8EBCDIC37C F 4 Oracle Database Gateway for APPC User s Guide Sample Implicit Versioning Definitions where ccccc is the version number of the DB2 IMAIN CALL definition queried after the previous DEFINE CALL updated DB2IMAIN There are two versions of the DB2I transaction definition in the PGA DD The original uses the old DCLEMP record format and starts transaction DB21 on the production CICS system The latest uses the NEWEMP record format and starts transaction DB21 on the test CICS system
224. n to the pgau trc file If a particular trace file is to be saved it must be copied to another file before the next invocation of GENERATE TRACE options can be specified in any order or combination and can also be specified with PKGEX operand on the same GENERATE statement mae a You must place at the end of the command Purpose Multiple PGAU commands can be grouped together for purposes of updating the PG DD and for rolling back all changes resulting from the commands in the group if any one statement fails No COMMIT processing is performed even if all commands within the group succeed You perform the COMMIT either by coding COMMIT commands in the PGAU script outside of GROUPs or by issuing COMMIT interactively to PGAU PGAU issues a savepoint ROLLBACK to conditions before processing the group if any statement within the group fails Syntax GROUP pgaustmt1 pgaustmt2 pgaustmtN Parameters pgaustmtN isa PGAU DEFINE REDEFINE or UNDEFINE statement Examples GROUP DEFINE DATA EMPNO PLSDNAME EMPNO USAGE PASS LANGUAGE IBMVSCOBOLIT 01 EMP NO PIC X 6 ee DEFINE CALL DB2IMAIN PKGCALL PGADB2I_MAIN PARMS EMPNO IN EMPREC OUT DEFINE TRANSACTION DB21I 2 18 Oracle Database Gateway for APPC User s Guide PGAU Commands HOST CALL DB2IMAIN DB2IDIAG SIDEPROFILE CICSPROD TPNAME DB2T LOGMODE ORAPLU62
225. n using the TCP IP communication protocol This parameter is optional on a gateway using SNA It specifies the APPC SYNCLEVEL of this transaction 0 or 1 The default value of 0 is assumed if this operand is omitted indicating the remote transaction program does not support synchronization A value of 1 indicates that CONFIRM is supported On a gateway using TCP IP The default of this parameter is 0 which is the only accepted value This is an optional parameter The default value is american_america we8ebcdic37c It is an Globalization Support name in the language_territory charset format It specifies the Globalization Support name in which the remote host data for all single byte character set fields in the transaction are encoded Note that if you are using TCP IP make sure that you set this parameter to american_america us7ascii This is an optional parameter The default value is jJapanese_japan jal dbcs It is an Globalization Support name in the language_territory charset format It specifies the Globalization Support name in which the remote host data for all multi byte character set fields in the transaction are encoded This is an optional parameter The default value is japanese_japan jal6dbcs It is an Globalization Support name in the language_territory charset format It specifies the Globalization Support name in which the local host data for all multi byte character set fields in
226. nable gateway server trace 8 11 enabling APPC trace from PL SQL 8 12 enabling through initsid ora 8 11 gateway server 8 10 purpose of initializing conversations 4 16 7 10 runtime 8 5 trace controls 8 6 suppressing 8 7 TIP 8 5 8 7 TRANSACTION correspondence on gateway using SNA 4 13 on gateway using TCP IP 7 7 transaction instance parameter on gateway using SNA 4 17 on gateway using TCP IP 7 11 Transaction Interface Package See TIP transaction socket transaction type for TCP IP 1 14 TRANSACTION tname 2 10 transaction types one shot persistent and multi conversational for SNA 1 10 transparency application 1 2 location on gateway using SNA 1 2 U UNDEFINE statement 3 6 F 7 USAGE ASIS D 8 USAGE PASS D 2 datatype conversion D 2 FILLER D 5 PIC9 D 4 PICG D 3 format conversion OCCURS DEPENDING ON D 7 OCCURS n TIMES D 6 USAGE SKIP D 8 utility dg4pwd 1 4 UTL_PG input parameters winsgbsiz C 2 Index 10 output parameters winsgblk C 3 package definition 1 5 parameters input and output C 2 PL SQL package 3 1 UTL_PG function C 1 MAKE NUMBER_TO_RAW_FORMAT C 6 MAKE _ RAW_TO_NUMBER_FORMAT C 5 NUMBER_TO_RAW C 4 NUMBER_TO_RAW and RAW_TO_NUMBER argument values C 11 NUMBER_TO_RAW_FORMAT C 8 RAW_TO_NUMBER C 3 RAW_TO_NUMBER_FORMAT C 8 WMSG C 10 WMSGCNT C 9 UTL_PG input parameters compname C 2 compopts C 2 envrnmnt C 2 mask C 2 maskopts C 2 nislang C 2 wind C
227. nana irea poaa eaa a a E EEEN E 1 PL SQL Package and TIP File Separation ooioicnicinnninnnnnnnncncnncnncncnrnrnnccncncoro ron cncnano ro ron cn crono ronca ciones E 2 Independent TIP Body Changes sismis ai aa aria n rasei deabia t E 2 Determine if a Specification Has Remained Valid ononicininicnnonicnnnnnnnnninconorornnnincororionininnos E 2 Dependent TIP Body or Specification Changes oocoocononcnconononennrnnnnneninnnnenenanoranoncnrnrnnnenrnaranannnnnnaso E 3 Recompile the TIP Bolivariana det aV ad pia eri E 4 Inadvertent Alteration of TIP SpecificatiON cocoonoomnosmnmmmrmramrerrarnnnrn rare nn narananannoro E 4 Administration Utility Samples Sample PGAU DEFINE DATA Statements oononnncccnconinonicinonononononononononononononononononcnnnnnonon rn conarncncncncnss F 1 Sample PGAU DEFINE CALL StatementS ooiciciconicicinnnnnnincononocnnconcnnonnonannconornonnnnnno ro ron conca nora caciones F 2 Sample PGAU DEFINE TRANSACTION Statement ccocicicionnnnoninconnnoncnnononornnnnncnnororoncininnoroncininnos F 2 Sample PGAU GENERATE Statement oocccccconononicinonononanincnonononcnoncnonononononcnnonnonononcnnannon corn cn na rncncncnnoss F 2 Sample Implicit Versioning Definitions onicinininininnnnnnnnnnnnncncnrrnccncanoro ran cn crono ron cn cn crono ron cn cronos F 3 Sample PGAU REDEFINE DATA StatementS ooocooincoconononcnnnncnnnccncnrornnnocananancnnaroranoncnrnrarnrnnnarananonoa F 6 Sample PGAU UNDEFINE Statements oooocicio
228. ncanenrrnrarnnornnnnnnos 1 17 Procedural Gateway Administration Utility Overview of PGA U na e a l E a a eaa a a a a E 2 1 COMMIT ROLLBACK Processidg ooooocioinononincnnnnnnincnconeninnnninnononon canino nan cono nnone non ananonano narco nronanan cn cnnnns 2 2 COMMIT Processing scsccscectiesceislescetassetesds asvveecaassedesbutssscedashsbadesasbubss dienes afssasturues et cdedeshiviatybeesed 2 2 ROLLBACK PHOCESSIN Berro ial ae A A EA 2 2 Invoking PGA vicio ic ai A E SA Selves dad ac dives a E Aia bt 2 3 Definitions and Generation in PGAU ococcncnincniononccnononncnnnonncnnnconcnnnnononnnonnnonnonncno nono non nano ncn nao nnnnnannnns 2 3 Process to Define and Testa TIP ii alar pablo 2 4 DAI NAM a 2 4 Definition Version iii oc ii aid dinates atlas octal hee eet 2 5 SO EAEE AE A EA che savisvbeeca late A aundesied sh hdester abranadee nat outer niaeweseat 2 5 PGAU Command 342205 2s 0200 scec8eg tsubeh i ecsteeiide a a ba thimsecba echo hill ned date ocean inland 2 6 CONNEC Disa hh i econ Sih sie eel hee tiated tel ne een Roe ea Ia 2 6 DEFINE CALL is 2 7 DEFINE DATA Lt E A A A A IA ID 2 8 DEFINE TRANSACTION lt A cs 2 10 DESCRIBE 14 ii caco hs 2 13 DISCONNECT octi niesna a rta ol tl ll ocads big 2 13 A a aaa a alneiie bin sletin a a aa aa a a 2 14 A a EN 2 14 GENERATE a AOS 2 15 GROUP A A e ea 2 18 FAQS Te A RR 2 19 PRINT ici da iia A e Ass 2 20 REDEFINE DATA nenioman eaa a alotbdibl 2 20 REM ercsieicidat benassi ities inanisiin
229. nd then logs the transaction into the logging server The gateway server stores the log information in a table called PGA_CC_PENDING on the logging server If a failure occurs during transaction processing the gateway server determines which error should be returned to the Oracle database The logging server is an Oracle database available to the gateway server for storing and accessing its commit confirm log information The logging server need not be the same Oracle database which acts as the integrating server Because the logging server is an integral component of gateway commit confirm operations the best place for it to reside is on the same system as the gateway server This allows the communication between the gateway server and the logging server to use interprocess communications providing a high speed low overhead local connection between the components There is a specific set of interactions that occur between the components They are a Oracle Database lt gt Gateway Server The Oracle database drives all actions by the gateway server At the request of the Oracle application the integrating server can instruct the gateway server to begin a new Oracle transaction start a commit sequence start a rollback sequence or start a forget sequence It can also call gateway remote procedural call RPC functions PGAINIT PGAXFER PGATERM on behalf of the Oracle application Gateway Server lt gt Logging Server The
230. ng the gateway Oracle database relationship The Oracle database can also be used for non gateway applications The gateway Oracle Database Gateway for APPC must be installed on a server that can run the required version of the operating system An OLTP The OLTP must be accessible from the gateway using your SNA or TCP IP communication protocol Multiple Oracle databases can access the same gateway A single system gateway installation can be configured to access more than one OLTP For gateways using TCP IP The only OLTP that is supported through TCP IP is IMS through IMS Connect The OLTP must be accessible to the system using the TCP IP protocol Multiple Oracle databases can access the same gateway A single system gateway installation can be configured to access more than one OLTP Multiple IMS systems can be accessed from an IMS Connect If you have a number of IMS Connect systems available any of these may be connected to one or more IMS systems Figure 1 2 illustrates the architecture of the Oracle Database Gateway for APPC using SNA or TCP IP as described in the previous section Introduction to Oracle Database Gateway for APPC 1 7 Communication with the Gateway Figure 1 2 Gateway Architecture Featuring SNA or TCP IP Protocol VSAM CICS Operating System DB2 VTAM APPC APPLICATION APE IMS DB CA IMS TM Other SNA Server Databases APPC Oracle Database
231. nit This initializes communications with the remote transaction program tip mode This accepts a mode selection parameter and puts the transaction program into either inquiry or update mode a tip ingr This returns an employee record for a given employee number a tip updt This accepts an employee record for a given employee number tip term This terminates communications with the remote transaction program The client application calls tip_init and then tip_mode to place the remote transaction program in inquiry mode which then scans employee records searching for some combination of attributes known to the client application and end user Some parameter on an inquiry call is then set to signal a change to update mode and the client application calls tip_updt to update some record The client application finally calls tip_term to terminate the remote transaction program The corresponding activity at the remote site is remote transaction program start mode selection exchange loop reading records a switch to update mode update one record remote transaction program end Such a remote transaction program is called persistent because it interacts until it is signalled to terminate The remote transaction program can be written to permit a return to inquiry mode and repeat the entire process indefinitely Multi Conversational Transactions A client application might need to get information from one transaction t
232. nment clause or NULL compname is the compiler name compopts are the compiler options or NULL nlslang is the zoned decimal code page in Globalization Support format wind is a warning indicator wmsgbsiz is the warning message block size in bytes wmsgblk is the warning message block This is an OUT parameter Defaults and Optional Parameters Table C 8 describes the defaults and optional parameters of the MAKE_RAW_TO_NUMBER_FORMAT function Table C 8 Default and Optional MAKE_RAW_TO_NUMBER_FORMAT Parameters Parameter Description maskopts null allowed no default value envrnmnt null allowed no default value compopts null allowed no default value Return Value A RAW 2048 format conversion specification for RAW_TO_NUMBI E y Error and Warning Messages If you receive an ORA xxxx error or warning message refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it MAKE_NUMBER_TO_RAW_FORMAT MAKE_NUMBER_TO_RAW_FORMAT makes a NUMBER_TO_RAW format conversion specification used to convert an Oracle number of declared precision and scale to a C 6 Oracle Database Gateway for APPC User s Guide UTL_PG Functions RAW byte string in the remote host internal format specified by mask maskopts envrnmnt compname compopts and nlslang Warnings are issued if enabled when the conversion specified conflicts with the conversion implied by the data or
233. nnnnonincnnonnnonincononincnnincnnoroncnnnanono ronca crono ron cn rn ora ro ran craneo F 7 Index Preface The Oracle Database Gateway for APPC provides Oracle applications seamless access to virtually any APPC enabled system including IBM mainframe data and services through Remote Procedure Call RPC processing Intended Audience Read this guide if you are responsible for tasks such as determining hardware and software requirements a installing configuring or administering an Oracle Database Gateway for APPC developing applications that access remote host databases through the Oracle Database Gateway for APPC using the SNA Communication Protocol or the TCP IP communication protocol a determining security requirements a determining and resolving problems Before using this guide to administer the gateway you should understand the fundamentals of your operating system and Oracle Database Gateways Documentation Accessibility Our goal is to make Oracle products services and supporting documentation accessible to all users including users that are disabled To that end our documentation includes features that make information available to users of assistive technology This documentation is available in HTML format and contains markup to facilitate access by the disabled community Accessibility standards will continue to evolve over time and Oracle is actively engaged with other market leading technology vendors to a
234. nt Application ooooininnnninininnnnnnnnnncnrnnnncnconerornnccncono ron cn corona roncnonos 4 14 Declaring TIP Variables enaena ie oaa re EA ee E aE aaia Toelae EE 4 14 Initializing the Conversation v c ccsccescccccceecescsevevescndsevevevssssesevveussbecsvvnsastetecbosestetssbossensassbressentatec s 4 16 Transaction Instance Parameter cccccessecssessssessscessecescecsscsesseeeecesseceseeceseecueseeeceeessaeseneeces 4 17 Overriding TIP Initialization cisccsc ites tccciesicesesdecsticccced stiocassttbsesevalssnsosveebeastecevessavtenstidstvoete 4 17 Security Considerations viii Saa a i i ade Eaa a 4 19 Exchanging Data uo ia 4 19 Terminating the Conversation omocnincononinonononanononcncncnononononononononononcnonononononon nano corn rnn or ie aE aeS 4 19 Error Handling AA O O AT 4 20 Granting Execuite AU Orina a daa e a dida 4 20 Ex cuting the Application iia eines iea as 4 20 APPC Conversation Sharing siise id ia 4 20 APPC Conversation Sharing Concepts cccccccsseseccscsssesesescscssesesescsesssesescscscssssseecscsssnsneseesees 4 21 APPC Conversation Sharing Usage ccccccccsssesesscscsesesesescscssesesescsesssesescscscssssseesscsssnsneseeeees 4 22 APPC Conversation Sharing TIP Compatibility ocioncicinininnnnacnnannnnncanncnonoccrarornnrnrorararnrncnoos 4 22 APPC Conversation Sharing for TIPs That Are Too Large cconnnicinnninnnnnnnininnnnannrnrncnccracorarnannos 4 23 APPC Conversation Sharing Example ccccc
235. nt Application Development TCP IP Only 7 5 Ensuring TIP and Remote Transaction Program Correspondence issue TCP IP send to write the data parameters to the remote transaction program The TIP must also cause the gateway to issue TCP IP receive when the remote transaction program issues TCP IP send The PGAU DEFINE CALL statement specifies how the generated TIP is to be called by the client application and which data parameters are to be exchanged with the remote host transaction for that call Each PGAU DEFINE CALL statement might specify the name of the TIP function one or more data parameters and the IN OUT mode of each data parameter Data parameters must have been previously defined with PGAU DEFINE DATA statements Refer to DEFINE CALL on page 2 7 in Chapter 2 Procedural Gateway Administration Utility and Sample PGAU DEFINE CALL Statements in Appendix F for more information PGAU DEFINE CALL processing stores the specified information in the PG DD for later use by PGAU GENERATE PGAU GENERATE then creates the following in the TIP package specification a declarations of public PL SQL functions for each CALL defined with PL SQL parameters for each DATA definition specified on the CALL a declarations of the public PL SQL data parameters The client application calls the TIP public function as a PL SQL function call using the functio
236. number in pga_call call Foreign key Copied from pga_cal1 cal11 for the referenced call when this transaction definition was inserted or updated pga_call The pga_call table relates all calls that are available for all defined transactions to a unique call id number and PL SQL remote procedural call RPC name One entry exists in this table for each PL SQL call defined in a DEFINE CALL statement One row per call duplicates are possible when multiple transactions make identical calls The plsrpc specification must be unique within the Oracle database which makes the calls and rows are uniquely distinguished by call The column type and content information for pga_call are presented in Table A 17 Table A 17 pga_call Column Type Content cname varchar2 48 Call name for PGAU reference Primary key Max length gt COBOL name string length Database Gateway for APPC Data Dictionary A 9 PG DD Active Dictionary Table A 17 Cont pga_call Column Type Content plsrpc varchar2 30 RPC call name for reference in PL SQL public procedure to be generated Max length gt PL SQL RPC name length updtdate date Audit trail date time of record s last update updtuser varchar2 30 Audit trail user id program which last updated this record version number 9 0 Version identification of this entry because multiple archived or invalid entries might exist and be kept for possib
237. o Oracle Database Gateway for APPC The Oracle Database Gateway for APPC enables users to initiate transaction program execution on remote online transaction processors OLTPs The Oracle Database Gateway for APPC can establish connection with OLTP using the SNA communication protocol The gateway can also use TCP IP for IMS Connect to establish communication with IMS TM through TCP IP The gateway provides Oracle applications with seamless access to IBM mainframe data and services through Remote Procedural Call RPC processing Refer to the Oracle Database Installation Guide and to the certification matrix on the My Oracle Support Web site for the most up to date list of certified hardware platforms and operating system versions The My Oracle Support Web site can be found at http metalink oracle com This chapter describes the architecture uses and features of the Oracle Database Gateway for APPC This chapter contains the following sections Overview of the Gateway a Features of the Gateway Terms Examples and Sample Files for the Gateway Architecture of the Gateway a Communication with the Gateway a RPC Functions a Overview of a Gateway Using SNA Overview of a Gateway Using TCP IP Overview of the Gateway The Oracle Database Gateway for APPC extends the RPC facilities available with the Oracle database The gateway enables any client application to use PL SQL to request execution of a remote transaction
238. o regenerate and recompile the TIP and its dependent client applications to restore correct operation Refer to Listing Dependency Management Information in the Oracle Database Advanced Application Developer s Guide for more information Tip Internals E 5 PL SQL Package and TIP File Separation E 6 Oracle Database Gateway for APPC User s Guide F Administration Utility Samples Use the following sample input statements and report output for the Procedural Gateway Administration Utility to guide you in designing your own PGAU statements This appendix contains these sample PGAU statements Sample PGAU DEFINE DATA Statements on page F 1 Sample PGAU DEFINE CALL Statements on page F 2 Sample PGAU DEFINE TRANSACTION Statement on page F 2 Sample PGAU GENERATE Statement on page F 2 Sample Implicit Versioning Definitions on page F 3 Sample PGAU REDEFINE DATA Statements on page F 6 Sample PGAU UNDEFINE Statements on page F 7 Sample PGAU DEFINE DATA Statements DEFINE DATA EMPNO PLSDNAME EMPNO USAGE PASS LANGUAGE IBMVSCOBOLIT DEFINE 0 1 EMP NO PIC X 6 1 DATA EMPREC PLSDNAME DCLEMP USAGE PASS LANGUAGE IBMVSCOBOLII INFILE emp cob where the file emp cob contains the following 01 DCLEMP 10 EMPNO PIC X 6 10 FIRSTNME 49 FIRSTNME LEN PIC S9 4 USAGE COMP 49 FIRSTNME TEXT PIC X 12 10 MIDINIT PIC X 1 10 LASTNAME 49 LASTNAME LEN PIC S9
239. ocedures are used PGAINIT which initializes transactions PGAXFER which transfers data PGATERM which terminates transactions Refer to Appendix B Gateway RPC Interface in this guide and to Remote Procedural Call Functions in Chapter 1 of the Oracle Database Gateway for APPC Installation and Configuration Guide for ALX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows for more information about gateway remote procedures dg4pwd dg4pwd is a utility which encrypts passwords that are normally stored in the gateway initialization file Passwords are stored in an encrypted form in the password file making the information more secure Refer to Passwords in the Gateway Initialization File in the security requirements chapter of the Oracle Database Gateway for APPC Installation and Configuration Guide for ALX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 and Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows for detailed information about how the dg4pwd utility works pg4tcpmap Tool This tool is applicable only when the gateway is using TCP IP support for IMS Connect Its function is to map SNA parameters such as Side Profile Name to TCP IP parameters such as O
240. ogram Refer to Ensuring TIP and Remote Transaction Program Correspondence on page 4 10 for a discussion of the correlation between TIPs and their respective remote transaction programs The PG DD contents define this correlation Procedural Gateway Administration Utility 2 1 COMMIT ROLLBACK Processing The PGA administrator or user defines the correlation between TIPs and the remote transaction program using the following PGAU commands also called statements PGAU DEFINE DATA statements which describe the data to be exchanged a PGAUDEFINE CALL statements which describe the exchange sequences a PGAU DEFINE TRANSACTION statements which group the preceding CALL and DATA commands together and describe certain aspects unique to the remote transaction program such as its network name or location a PGAU GENERATE statement which the PGA administrator or user uses to specify and create the TIP specifications after the TIP transaction correlation has been defined in the PG DD Additional PGAU commands needed to alter and delete definitions in the PG DD are described in PGAU Commands later in this chapter The PGAU commands are known collectively as Procedural Gateway Definition Language PGDL Any references to PGDL are to the collection of PGAU commands defined in this chapter PGAU provides editing and spooling facilities and the ability to issue SOL commands Caution Do not use PGAU inste
241. oie 8 6 Generating Runtime Data Conversion Trace and Warning Support occccococcnnnonncnonennerarnnananaoos 8 6 Controlling TIP Runtime Conversion Warnings cococicoonononnnnnonanananonananananonononononononononcnnararnrncncnion 8 6 Controlling TIP Runtime Function Entry Exit Tracing ccccococicinnonnnnnnnonaraninononanananononononanononononcnos 8 7 Controlling TIP Runtime Data Conversion Tracing ocncncnnnnonononananinonannnananonononononononononononononononos 8 7 Controlling TIP Runtime Gateway Exchange Tracing cococinicionnnincnnonenconanonionininnanananononananananonos 8 7 Suppressing TIP Warnings and Tracing 0 c cece esses cece eens nnonononan conan oran nan rn aran nnn conan aran 8 7 Problem Analysis of Data Conversion and Truncation Errors ooonicononcnnononenennrnnnrnrrenanarnnrnnnos 8 8 Gateway Server Tracing i cocino di iio siii laces tensa sveleavanavesadivnesbvelearaesvecdatvacvicassstacens 8 10 Defining the Gateway Trace Destination ccccccscesssssesesescsessesesescsssesescsessssseseecscessnseeceseees 8 10 Enabling the Gateway Trace sc scicc tics hisses iiisge areir a Dela uel da ra oane E cti 8 11 Enabling the Gateway Trace Using Initialization Parameter ooococococicanicinnononinnnananinninonos 8 11 Enabling the Gateway Trace Dynamically from PL SQL cocinocinicicininnnnnnacaninonincnaninnoracooos 8 12 Database Gateway for APPC Data Dictionary PG DD Environment Dictiomary cccccceesccseseessseseseses
242. ol pg4tcpmap whose purpose is to map the information from your SNA Side Profile Name to the TCP IP host name and Port Number Note When your communications protocol is TCP IP only IMS is supported as the OLTP The following terms and definitions are used throughout this guide Gateway Initialization File This file is known as initsid ora and it contains parameters that govern the operation of the gateway If you are using the SNA protocol refer to Appendix A Gateway Initialization Parameters for SNA Protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows for more information If your protocol is TCP IP refer to Appendix B Gateway Initialization Parameters for TCP IP Communication Protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Introduction to Oracle Database Gateway for APPC 1 3 Terms Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows Gateway Remote Procedure The Oracle Database Gateway for APPC provides prebuilt remote procedures In general the following three remote pr
243. ompiled 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 a Oracle ships maintenance which affects the TIP body or a Oracle ships maintenance for the UTL_RAW or UTL_PG conversion functions upon which the TIP body relies Refer to Appendix C The UTL_PG Interface for more detailed information about these functions if the remote host network or program location parameters have changed Refer to DEFINE TRANSACTION in Chapter 2 Procedural Gateway Administration Utility for more information 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 on page 2 15 in Chapter 2 Procedural Gateway Administration Utility for a discussion of file identification Independent TIP Body Changes 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
244. on development content and purpose on gateway using SNA 4 3 content and purpose on gateway using TCP IP 7 3 compiling 3 7 content documentation tipname doc 3 8 content file sections GENERATION Status 3 8 TIP Default Calls 3 8 TIP Transaction 3 8 TIP User Calls 3 8 TIP User Declarations 3 8 TIP User Variables 3 8 control file 2 2 controlling runtime conversion warnings 8 6 runtime data conversion tracing 8 7 runtime function tracing 8 7 runtime gateway exchange tracing 8 7 conversation sharing used to circumvent large TIPs 4 23 conversion 1 3 4 25 7 15 converting PL SQL datatypes to RAW 1 9 creating 3 1 custom TIP writing E 1 customized interface for each remote host transaction RTP 4 6 DATA correspondence 4 10 on gateway using TCP IP 7 4 datatype conversion support for COBOL D 2 declaring variables to create a TIP 4 14 7 8 defining and generating 3 6 defining with PGAU 2 4 definition 1 5 definition errors 8 1 dependent TIP body or specification changes E 3 diagnostic parameters 4 25 driver procedures on gateway using SNA 1 14 on gateway using TCP IP 1 19 flexible call sequence 4 12 four steps to generate on gateway using SNA 1 12 on gateway using TCP IP 1 17 functions in Oracle database 1 9 generated by PGAU 4 2 granting privileges to use 3 1 4 27 7 16 independent TIP body changes E 2 initializations 4 18 7 12 overriding 4 17 on gateway using TCP IP 7 11 initia
245. ons for the symbols Table D 2 COBOL Symbol Definitions COBOL Symbols Oracle Definition of COBOL Symbols Data Content BB blank 1 byte SBCS or 2 bytes DBCS depending on USAGE 0 zero 1 byte SBCS i forward slash 1 byte SBCS Ge double byte Datatype Conversions D 3 Conversion Edited positions in COBOL statement data received from the remote host are converted by PGAU along with the entire field and passed to the client application in the corresponding PL SQL VARCHAR2 output variable When editing symbols are present they are interpreted to mean the remote host field contains the COBOL data content and length indicated The editing positions are included in the length of the data field but conversion of all field positions is processed by PGAU as a single string and no special scanning or translation is done for edited byte positions Edited positions in COBOL statement data sent to the remote host are converted by PGAU along with the entire PL SQL VARCHAR2 input variable passed from the client application Table D 3 provides an example of how PGAU converts COBOL datatypes Table D 3 COBOL PGAU Conversion COBOL Datatype Description of Conversion by PGAU PIC XXXBBXX Is an alphanumeric field 7 bytes in length and would be converted in a single UTL_RAW CONVERT call No testing or translation is done on the contents of the byte positions indicated by B While COBOL language rules indicate that
246. ortant 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 For information about PL SQL Packages refer to the Oracle Database PL SQL Language Reference For information about PGA Application Concepts refer to the following chapters in this guide If your communication protocol is SNA refer to Chapter 4 Client Application Development SNA Only If your communication protocol is TCP IP refer to Chapter 7 Client Application Development TCP IP Only For information about PGA RPC Interface refer to Appendix B Gateway RPC Interface Tip Internals E 1 PL SQL Package and TIP File Separation a For information about PGA UTL_PG Interface refer to Appendix C The UTL_PG Interface PL SQL Package and TIP File Separation 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 Oracle Database Advanced Application Developer s Guide and the Oracle Database PL SQL Language Reference for more information Also refer to GENERATE on page 2 15 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 rec
247. ou are writing your own TIP or debugging a client application that calls the TIP The client application calls the three TIP functions with input and output arguments In the example the client application passes empno an employee number to the remote transaction and the remote transaction sends back emprec an employee record Table 4 1 demonstrates the logic flow between the PL SQL driver the TIP and the gateway using the example CICS DB2 transaction Table 4 1 Logic Flow of CICS DB2 Example Procedures Established Between the Gateway and the Remote Transaction Client Application Oracle TIP mainframe calls tip_init Calls PGAINIT Gateway sets up control blocks and issues APPC ALLOCATE Mainframe program initiates calls tip_main Calls PGAXFER to send Gateway issues APPC SEND to the empno and receive mainframe Mainframe RECEIVE emprec completes Mainframe performs application logic and issues APPC SEND back to gateway The gateway issues APPC RECEIVE receive completes Mainframe issues APPC TERM calls tip_term Call PGATERM Gateway cleans up control blocks A client application which utilizes the gateway to exchange data with a remote host transaction performs some tasks for itself and instructs the TIP to perform other tasks on its behalf The client application designer must consequently know the behavior of the remote transaction and how the TIP facilitates the exchange 4 2 Orac
248. override values set in the Side Information profile PROFNAME must be set and cannot be blank or null Gateway RPC Interface B 3 Calling Gateway Functions to Execute Transaction Programs PGAXFER 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 PGA N T 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 Datatype Type Description CONVID IN RAW 12 SENDBUF IN RAW 32763 SENDBUFL IN BINARY_INTEGER SENDLNS IN RAW 1024 RECVBUF OUT RAW 32763 B 4 Oracle Database Gateway for APPC User s Guide 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 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 si
249. owing SET TRACE_LEVEL 255 SET LOG_DESTINATION logdest where logdest is the directory path for the trace output The logfile is usually in SORACLE_HOME dg4appc 1log for Microsoft Windows and SORACLE_ HOME dg4appc 1log for UNIX based systems Refer to the earlier discussion about Problem Analysis of Data Conversion and Truncation Errors on page 8 8 for more information Note Misspelled parameter names in initsid ora are not detected The parameter is ignored Once these two steps are completed the gateway opens the specified trace file during initialization Each session on this system identifier writes a trace file as specified by the SET LOG_DESTINATION parameter described in Step 2 above If a directory path was specified each trace file has a name of the form sid_pid log where sidis the gateway sid and pid is the operating system process ID of the gateway server expressed in decimal Enabling the Gateway Trace There are two ways to enable the gateway server tracing The first is to set the tracing options in the gateway initialization file initsid ora The second is to use the additional PGA remote procedural call RPC function PEATCTL to dynamically control the tracing from within the Oracle application The first method causes tracing to be performed for all users of the gateway system identifier and is recommended only when the use of the gateway system identifier can be limited to
250. p pkh pgtflip pkb and pgtflipd sql Remote Host Transaction Types From a database gateway application perspective there are three main types of remote host transactions transaction socket persistent socket non persistent socket You should be familiar with the remote host transaction types Refer to the IBM IMS Connect Guide and Reference for a full description of these transaction types Ensuring TIP and Remote Transaction Program Correspondence A remote host transaction program and its related TIP with client application must correspond on two key requirements Parameter datatype conversion which results from the way in which transaction DATA is defined Refer to Appendix D Datatype Conversions for a discussion of how PGAU generated TIPs convert data based on the data definitions a TCP IP send receive synchronization which results from the way in which transaction CALLs are defined These DATA and CALL definitions are then included by reference in a TRANSACTION definition Make certain that the SIDEPROFILE name has been mapped to TCP IP and IMS Connect attributes using the pg4tcpmap tool DATA Correspondence Using data definitions programmed in the language of the remote host transaction the PGAU DEFINE DATA command stores in the PG DD the information needed for PGAU GENERATE to create the TIP function logic to perform a all data conversion from PL SQL IN par
251. passing and handling within the client application thus sharing the declarations created by PGAU GENERATE In this example the following PGAU DEFINE CALL statement must be issued to define the TIP public function DEFINE CALL DB2IMAIN PKGCALL pgadb2i_main PARMS empno IN emprec OUT Flexible Call Sequence 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 field1 field5 field6 field7 field8 field10 APPC SEND 5 fields APPC RECEIVE 1 fields APPC SEND 1 field APPC RECEIVE 3 fields The resulting TIP application call sequence could be tip_call1 parml OUT lt APPC SEND fieldl from remote TP parm2 OUT lt APPC SEND field2 from remote TP parm3 OUT lt APPC SEND field3 from remote TP tip_call2 parm4 OUT lt APPC SEND field4 from remote TP parm5 OUT lt APPC SEND field5 from remote TP tip_call3 parm6 IN OUT gt APPC RECEIVE field6 in remote TP lt APPC SEND field7 from remote TP tip_call4 parm8 IN gt APPC RECEIVE field8 into remote TP parm9 IN gt APPC RECEIVE field9 into remote TP parml0 IN gt APPC RECEIVE field10 into remote TP To define these four public functions to the TIP four PGAU DEF
252. pe values must be assigned to the override subfields and the override record variable must be passed on the TIP initialization call from the client application For example my_overrides pgtflip override_Typ declaration my_overrides oltpname IVINO swap to production IMS my_overrides tranname IVINV new transaction name BEGIN rc pgtflip pgtflip init trannum my_overrides init Within the TIP override attributes are checked for syntax problems and passed to the gateway server Security Considerations The security requirements of the default and overridden OLTPs must be the same because the same gateway server is used in either conversation as dictated by the database link names in the PGA RPC calls The gateway server startup security mode is set at gateway server initialization time and passed unchanged to the OLTP at TIP or conversation initialization time Exchanging Data The client application should pass the transaction instance number returned from a previous tip_init call to identify which remote transaction program is affected and to identify any client application data parameters to be exchanged with the remote transaction program In this IMS Connect inquiry example we pass an employee number and receive an employee record back rc pgtflip pgtflip_main trannum transfer data mesgin input parameter de mesgout output parameter Terminating the Conversation The clien
253. pecified here determines the order in which they are created by GENERATE but not necessarily the order in which they might be called by an application VERS callvers is an optional specific version number of the call definition if not the latest The relative position of each cname in its left to right sequence is the seq column in pga_trans_calls For example CALL cnamel cname2 cname3 pga_trans_calls seq 1 2 3 Specifies the name of the host environment for this transaction for example IBM370 If this parameter is omitted IBM370 is assumed IBM370 is the only environment supported by this version of PGAU 2 10 Oracle Database Gateway for APPC User s Guide PGAU Commands Table 2 3 Cont DEFINE TRANSACTION Parameter Descriptions Parameter Description SIDEPROFILE name LUNAME name TPNAME name This parameter is optional for a gateway using SNA but if omitted the user must specify the parameters for LUNAME TPNAME and LOGMODE It specifies the name of an SNA Side Information Profile which directs the APPC connection to the transaction manager This name can be 1 to 8 characters in length Name values can be alphanumeric with and characters only if unquoted Quoted values can contain any character and delimited by quotes or apostrophes Case is preserved for all values This parameter is mandatory for a gateway using the TCP IP connection
254. perform the initialization logic programmed in the TIP initialization section a To cause the TIP init function to call the PGAINIT remote procedural call RPC which in turn establishes communication with the remote transaction program RTP and returns a transaction instance number to the application Optionally calls to initialize the conversation can be used to a Override default RHT OLTP identification network address attributes and conversation security user ID and password Specify what diagnostic traces the TIP is to produce Refer to Chapter 8 Troubleshooting for more information about diagnostic traces PGAU generated TIPs provide four different initialization functions that client applications can call These are overloaded functions which all have the same name but vary in the types of parameters passed Three initialization parameters are passed a The transaction instance number for RHT socket file descriptor The tranuse parameter is required on all TIP initializations TIP diagnostic flags for TIP runtime diagnostic controls The tipdiag parameter is optional Refer to Chapter 8 Troubleshooting for a discussion of TIP diagnostics TIP default overrides for overriding OLTP and network attributes The override parameter is optional The following four functions are shown as they might appear in the TIP Content documentation file Examples of client application use are provided later TYP
255. pno employee number 7 DCLEMP return employee record Terminating the Conversation The client application calls the TIP termination function as if it were any local PL SQL function For example term 1 indicate term called rc pgadb2i pgadb2i_term tranuse 0 terminate normally Client Application Development SNA Only 4 19 Executing the Application 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 may be forgotten Error Handling The client application should include an exception handler that can clean up any active APPC conversations before the client application terminates The sample client application provided in pgadb2id sql contains an example of exception handling Gateway exceptions are reported in the range PGA 20900 to PGA 20999 When an exception occurs the TIP termination function should be called for any active conversations that have been started by prior calls to the TIP initialization function For example EXCEPTION WHEN OTHERS THEN IF term 0 THEN terminate function not called yet rc pgadb2i pgadb2i_term tranuse 1 terminate abnormally END IF RAISE The remote transaction should also include provisions for error handling and debugging such as writing debugging information to the CICS temporary storage que
256. port format wind is a warning indicator The UTL_PG Interface C 3 UTL_PG Functions Table C 3 Cont RAW_TO_NUMBER Function Parameters Parameter Description wmsgbsiz is the warning message block size in bytes wmsgblk is the warning message block This is an OUT parameter Defaults and Optional Parameters Table C 4 describes the default and optional parameters of the RAW_TO_NUMBER function Table C 4 Optional and Default Parameters of the RAW_TO_NUMBER Function Parameters Description maskopts null allowed no default value envrnmnt null allowed no default value compopts null allowed no default value Return Value An Oracle number corresponding in value to r Error and Warning Messages If you receive an ORA xxxx error or warning message refer to the Oracle Database Error Messages for an explanation and information about how to handle it NUMBER_TO_RAW NUMBER_TO_RAW converts an Oracle number n of declared precision and scale into a RAW byte string in the remote host internal format specified by mask maskopts envrnmnt compname compopts and nlslang Warnings are issued if enabled when the conversion specified conflicts with the conversion implied by the data or when conflicting format specifications are supplied For detailed information about the mask maskopts envrnmnt compname and compopts arguments refer to NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values on page C 11 S
257. privileges on the rtrace and ptrace procedures Refer to the Configuring PGAU section in the chapter appropriate for your communications protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows and the Oracle Database Rules Manager and Expression Filter Developer s Guide for more information For example on Microsoft Windows C gt sqlplus pgaadmin pw database_specification_string SQL gt grant execute on pgaadmin purge_trace to tip_user_userid SQL gt grant execute on pgaadmin read_trace to tip_user_userid On UNIX based systems sqlplus pgaadmin pw database_specification_string SQL gt grant execute on pgaadmin purge_trace to tip_user_userid SQL gt grant execute on pgaadmin read_trace to tip_user_userid After a TIP has been developed the TIP user must be granted execute privileges on the TIP by the TIP owner The TIP owner is usually PGAADMIN but can be another user who has been granted either the PEDDDEF or PGDDGEN roles For example on Microsoft Windows C gt sqlplus tip_owner pw database_specification_string SQL gt grant execute on tipname to tip_user_userid On UNIX based systems sqlplus tip_owner pw database_specification_string SQL gt grant exe
258. pulating the PGA_TCP_IMSC Table 000 0 cesses eens ceceesecesseseecsssenesecseseseenseeasananees 6 2 Before You Run the pg4tcpmap Tool peii rairai 6 4 pg4tcpmap Tool Commands sneseno kie a a o e h E AE 6 6 Inserting a Row into the PGA_TCP_IMSC Table oconioinonocociccnnonininnnoconananononononanononononcnnanacncncnoso 6 6 Deleting Rows from the PGA_TCP_IMSC Table cooocinininnninnononoconononononcnananononononanonononononononcncncnos 6 6 Querying the PGA_TCP_IMSC Table piian ee ae E e E E E E EEEE 6 7 Client Application Development TCP IP Only Overview of Client Application oococininnnnncicnnnnininnnnnanonancncncnnononnonrncononoco nono corona rn raro ora ra nero rnn aaron 7 1 Preparing the Client Application oocoinnnnnnnnnnnninicinnnnnnnonincncnnononncncncononannrn eeoa e a a E Eina 7 3 TIP Content and Purpose aro ias ls 7 3 Remote Host Fransaction TypeSs gists ii laa diodes 7 4 Ensuring TIP and Remote Transaction Program Correspondence ccicicnininnnnnnnnicnonnacicinnnnaneso 7 4 DATA Correspondence saen a a eer aeea raar SERAS SE eaaa EE ER ADLA Nea ESAE chose OPA ETE EESE 7 4 GALL Correspondente iio date du add IA dba at E ER R 7 5 Flexible Call Segu nt n Dana sre costaria Laia od IS guseseets It R tees 7 6 Call Correspondence Order RestrictiOMS ooocnconononenonncnnncnnnnrnrenecanannanennrnrannenonananarnarararannnnnnos 7 7 TRANSACTION Correspondence mms dd 7 7 Calling the TIP from the Client Application cece cceene
259. r to the Oracle Database Error Messages for an explanation and information about how to handle it MAKE_RAW_TO_NUMBER_FORMAT MAKE RAW_TO_NUMBER_FORMAT makes a RAW_TO_NUMBER format conversion specification used to convert a RAW byte string from the remote host internal format specified by mask maskopts envrnmnt compname compopts andnlslang into an Oracle number of comparable precision and scale Warnings are issued if enabled when the conversion specified conflicts with the conversion implied by the data or when conflicting format specifications are supplied This function returns a RAW value containing the conversion format which can be passed to UTL_PG RAW_TO_NUMBER_FORMAT For detailed information about the mask maskopts envrnmnt compname and compopts arguments refer to NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values on page C 11 The UTL_PG Interface C 5 UTL_PG Functions Syntax function MAKE_RAW_TO_NUMBER_FORMAT mask IN VARCHAR2 maskopts IN VARCHAR2 envrnmnt IN VARCHAR2 compname IN VARCHAR2 compopts IN VARCHAR2 nlslang IN VARCHAR2 wind IN BOOLEAN wmsgbsiz IN BINARY_INTEGER wmsgblk OUT RAW RETURN RAW Where Table C 7 describes the parameters in this function Table C 7 MAKE_RAW_TO_NUMBER_FORMAT Function Parameters Parameter Description mask is the compiler datatype mask maskopts are the compiler datatype mask options or NULL envrnmnt is the compiler enviro
260. r 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 PGAXF ER 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 NIT Upon successful completion of this function the previous call to PGA conversation is d
261. ram that was executed 5 8 Oracle Database Gateway for APPC User s Guide 6 PG4TCPMAP Commands TCP IP Only This chapter contains the commands and instructions necessary to operate the pg4tcpmap tool This tool allows relevant parameters to map to a gateway using TCP IP support for IMS Connect The tool will be used to populate the PGA_TCP_IMSC table This chapter contains the following sections Preparation for Populating the PGA_TCP_IMSC Table on page 6 1 Overview on page 6 1 Populating the PGA_TCP_IMSC Table on page 6 2 Before You Run the pg4tcpmap Tool on page 6 4 pg4tcpmap Tool Commands on page 6 6 Preparation for Populating the PGA_TCP_IMSC Table Overview If your gateway is using TCP IP support for IMS Connect then you must use the pg4tcpmap tool to prompt PGAINIT to provide the required TCP IP parameters as input The pg4tcpmap tool must be run before executing any PL SQL gateway statements in order to populate the PGA_TCP_IMSC table which utilizes the corresponding TIPs Note that you do not need to rerun the pg4tcpmap tool for additional IMS transactions if they share the same IMS Connect attributes The PGA_TCP_IMSC table was created when you executed the SORACLE_HOME dg4appc admin pgaimsc sql1 script on Microsoft Windows or SORACLE_HOME dg4appc admin pgaimsc sql script on UNIX based systems during your gateway configuration If you need further information
262. rameters supplied by the user or client application when the TIP initialization function is called Refer to Initializing the Conversation on page 4 16 and Overriding TIP Initializations on page 4 17 for more details Exchange data with the RHT using the TIP user function one call As previously discussed a one shot remote host transaction only accommodates a single data exchange and upon completion of that exchange the RHT terminates on its own The client application consequently needs only to execute a single call to the user defined TIP function to cause the data exchange Refer to the TIP content documentation file in SORACLE_HOME dg4appc demo CICS on Microsoft Windows or SORACLE_ HOME dg4appc demo C1ICS on UNIX based systems for the specific TIP RHT for the exact syntax of this call The client application should initialize values into IN or IN OUT parameter values before calling the TIP function call These are the same variables that were declared above when you declared the RHT TIP datatypes to be exchanged All TIP function calls return a 0 return code value and all returned user gateway data values are exchanged in the function parameters Any exception conditions are raised as required and can be intercepted in an exception handler Upon return from the TIP function call the client application can analyze and operate on the IN OUT or OUT parameter values These are the same variables that were dec
263. ran_A and subsequently write or lookup information from another tran_B This is possible with a properly written client application and TIPs for tran_A and tran_B In fact any number of transactions might be concurrently controlled by a single client application All transactions could be read only with the client application retrieving data from Client Application Development SNA Only 4 5 Customized TIPs for Each Remote Host Transaction each and consolidating it into a local Oracle database or displaying it in an Oracle Form Alternatively a transaction could be capable of operating in different modes or performing different services depending on what input selections were supplied by the client application For example one instance of tran_C can perform one service while a second instance of tran_C performs a second service Each instance of tran_C would have its own unique conversation with the client application and each instance could have its own behavior one shot or persistent depending on the nature of the service being performed Customized TIPs for Each Remote Host Transaction Each remote host system might have hundreds of remote transaction programs RTPs which a user might want to call Each remote transaction program is different passes different data and performs different functions The interface between the user and each remote transaction program must consequently be specialized and customized to the user
264. rans Column Type Content tname varchar2 64 Transaction name as defined by the customer Primary key Max length gt APPC TPname string length version number 9 0 Version identification of this entry it exists in the table because multiple archived or invalid entries might exist and be kept for possible future reactivation Primary key Set from an Oracle sequence object for transaction version inserted into the PG DD updtdate date Audit trail date time record last updated updtuser varchar2 30 Audit trail user ID program which last updated this record trans number 9 0 PGA Transaction number used for the define call define data and define transaction statements Foreign key pga_trans_values trans pga_trans_calls trans Set from an Oracle sequence object for transaction inserted into the PG DD pga_trans_attr The pga_trans_attr table relates a character string defining the transaction attributes supported by PGA to pga_trans_values entries through an attribute id number and type The pga_trans_attr table is also used for integrity checks of transaction attributes when new transactions are being defined There is an entry in the pga_trans_attr table for each transaction attribute name All possible transaction attribute names supported by PGA on any defined transaction are specified There is one row for each attribute and no duplicates are allowed Table A 14 presents the colu
265. re currently supported oltpuser can be set to override the user ID used to initialize the conversation with the OLTP oltppass can be set to override the password used to initialize the conversation with the OLTP The security overrides have an effect only if PGA_SECURITY_TYPE PROGRAM is specified in the gateway initialization file and the OLTP system is configured to accept a user ID and password on incoming conversation requests The transync IMS Connect SYNCLEVEL and trann1s Globalization Support character set are defined in the override record datatype but are reserved for future use The RHT SYNCLEVEL and Globalization Support name cannot be overridden The client application might override the default attributes at TIP initialization for the following reasons a to start a different version of the RHT such as production instead of test to change the location of the OLTP containing the RHT if the OLTP was moved due to migration or a switch to backup configuration Client applications requiring overrides can use any combination of override and initialization parameters and might alter the combination at any time without regenerating the TIP or affecting applications that do not override parameters 7 12 Oracle Database Gateway for APPC User s Guide Exchanging Data To override the TIP defaults an additional client application record variable must be declared as override_Typ dataty
266. rent package name in the database Only new DEFINE TRANSACTION statements were needed to make use of APPC conversation sharing The CALL and DATA definitions were used as is This means the old TIP rhtAsc is still defined as it was and might still be too large to compile 4 24 Oracle Database Gateway for APPC User s Guide Application Development with Multi Byte Character Set Support Example 3 If you performed Sample 2 but you still believe that the TIP may be too large to compile try this 1 DEFINE TRANSACTION rhtABC calls menu_A tpname RHTA DEFINE TRANSACTION rhtB calls query_B tpname RHTA 1 1 DEFINE TRANSACTION rhtCU calls update_C tpname RHTA DEFINE TRANSACTION rhtCS calls select_C tpname RHTA 1 TIP rhtABC has had three functions removed so it is now smaller and more likely to compile TIP rhtB has one function and TIP rhtC has been separated into two TIPs even though the corresponding host functions remain in a single RHT The client application calls these functions as follows rc rhtB rhtB_init tranuse rc rhtABC pick tranuse choice rc rhtB query tranuse input rc rhtCU update tranuse record rc rhtCS select tranuse record rc rhtABC rhtABC_term tranuse A different TIP is used for initialization illustrating that all TIPs contain the init and term functions and because the DEFINE TRANSACTION statements all spec
267. rmation about PGAU All parameter names in this section are taken from a file called pgadb2i ct1 in the SORACLE_HOME pga4appc demo CICs directory on Microsoft Windows or in the SORACLE_HOME pga4appc demo CICS directory on UNIX Based systems Py Py Steps to Writing a TIP on a Gateway Using SNA Follow these steps to write a TIP Step 1 Create a control file The user writes the control files The control file has four main types of PGAU commands 1 DEFINE DATA This is used to define input and output fields using COBOL data definitions Sample define data define data empno plsdname empno usage pass language ibmvscobolii infile empno cob 1 12 Oracle Database Gateway for APPC User s Guide Overview of a Gateway Using SNA 2 DEFINE CALL This is used to define PL SQL functions calls to be generated as part of the package a Sample define call define call db2imain pkgcall pgadb2i_main parms empno in emprec out 3 DEFINE TRANSACTION This is used to group the preceding functions and specify other parameters on which the TIP depends Sample define transaction define transaction db2i call db2imain db2idiag sideprofile CICSPGA tpname DB2T logmode orap1u62 synclevel 0 nls_language american_america we8ebcdic37c 4 GENERATE This is used to generate the TIP specification files from the previously stored data call and transaction
268. rogram RTP facilities to be called and the data to be exchanged on each call You will then define the following and store them in the PG DD m DEFINE DATA a DEFINE CALL a DEFINE TRANSACTION Refer to Chapter 3 Creating a TIP for specific definition steps and for the actual creation and generation of a TIP TIP Content and Purpose The content of a PGAU generated TIP reflects the calls available to the remote host transaction and the data that has been exchanged Understanding this content helps when designing and debugging client applications that call the TIP A TIP is a PL SQL package and accordingly has two sections 1 A Package Specification containing a Public function prototypes and parameters and 2 A Package Body containing a Private functions and internal control variables a Public functions Client Application Development SNA Only 4 3 Understanding the Remote Host Transaction Requirements a Package initialization following the last public function The purpose of the TIP is to provide a PL SQL callable public function for every allowed remote transaction program interaction A remote transaction program interaction is a logically related group of data exchanges through one or more PGAXFER RPC calls This is conceptually similar to a screen or menu interaction in which several fields are filled in the enter key is pressed and several fields are returned to the user Carrying the analog
269. roles For example For Microsoft Windows C gt sqlplus tip_owner pw database_specification_string SQL gt grant execute on tipname to tip_user_userid For UNIX based systems sqlplus tip_owner pw database_specification_string SQL gt grant execute on tipname to tip_user_userid where database_specification_string is the Oracle Net identifier for the Oracle database where the gateway UTL_RAW and UTL_PG components were installed This is the same Oracle database where the TIPs are executed and where grants on the TIPs are performed from the TIP owner user ID A SQL script for performing these grants is provided in the SORACLE_HOME dg4appc admin directory for Microsoft Windows and SORACLE _ HOME dg4appc admin in the directory for UNIX based systems The pgddausr sql script performs the grants for private access to the packages by a single TIP user If private grants are to be used the pgddausr sql script must be run once for each TIP user s user ID To run these scripts use SQL Plus to connect to the Oracle database as user PGAADMIN From SQL Plus run the pgddausr sal script from the SORACLE_HOME dg4appc admin directory on Microsoft Windows or SORACLE _ HOME dg4appc admin directory on UNIX based systems The script performs the necessary grants as previously described You are prompted for the required user IDs passwords and database specification strings If you are using private grants repeat
270. rom an Oracle sequence object for transaction inserted into the PG DD attr number 9 0 Attribute id from pga_trans_attr attr Primary key Set from an Oracle sequence object for each supported transaction attribute inserted into the PG DD A 8 Oracle Database Gateway for APPC User s Guide PG DD Active Dictionary Table A 15 Cont pga_trans_values Column Type Content numval number 9 0 Attribute s numeric value for example for a given transaction s SYNCLEVEL attribute 0 charval varchar2 64 Attribute s character value for example a given transaction s TPNAME attribute dateval date Attribute s date value Probably always null included for completeness pga_trans_calls The pga_trans_calls table relates all calls available with any single transaction to each specific call definition through a call ID number An entry exists in the pga_trans_calls table for each PL SQL call referenced in a transaction definition through the CALL cname operand One row per transaction call no duplicates The column type and content information for pga_trans_cal1s is presented in Table A 16 Table A 16 pga_trans_calls Column Type Content trans number 9 0 Transaction id number from pga_trans trans Primary key Set from an Oracle sequence object for transaction inserted into the PG DD seq number 9 0 Sequence number of this call Primary key call number 9 0 Call id
271. rsion is assumed Active Dictionary Sequence Numbers Because the active dictionary is constantly changing the identifying numbers needed to join active dictionary entries together must also change To support this requirement PG DD installation creates the following Oracle sequence objects Table A 12 lists the Oracle sequence objects and their descriptions Table A 12 Active Dictionary Oracle Sequence Object Descriptions Oracle Sequence Objects Description pga transeq Transaction id tag pga tranvers Transaction Version id tag pga tattrseq Transaction Attribute id tag pga callseg APPC Call id tag pga callvers Call Version id tag pga parmseq APPC Call Parameter id tag pga dataseq Data id tag pga fieldseq Data subfield id tag pga datavers Data Version id tag pga dattrseq Data Attribute id tag Active Dictionary Tables Following is a list of active dictionary tables pga_trans pga_trans_attr pga_trans_values pga_trans_calls pga_call pga_data pga_fields pga_data_attr pga_data_values pga_trans One row exists in the PGA_TRANS table for each user transaction The row is created by aPGAU DEFINE TRANSACTION statement and used by a PGAU GENERATE statement to create the PL SQL package TIP A 6 Oracle Database Gateway for APPC User s Guide PG DD Active Dictionary Table A 13 presents the column type and content information for PGA_ TRANS Table A 13 pga_t
272. s a Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 a Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows You might also need Oracle Database 11g and Oracle Net documentation The following is a useful list of the Oracle publications that may be referenced in this book a Oracle Database Installation Guide a Oracle Database Administrator s Guide Oracle Database Rules Manager and Expression Filter Developer s Guide a Oracle Database Concepts Oracle Database Error Messages Oracle Database Net Services Administrator s Guide Refer to the Oracle Technical Publications Catalog and Price Guide for a complete list of documentation provided for Oracle products Legacy Compilers Examples in this guide use the compiler name parameter value IBMVSCOBOL which represents the IBM VS COBOL II compiler Although the IBM VS COBOL II compiler is no longer supported the string IBMVSCOBOLIT should still be used and the supported COBOL compiler will be called Conventions The following text conventions are used in this document Convention Meaning boldface Boldface type indicates graphical user interface elements associated with an action or terms defined in text or the glossary xii Convention Meaning italic Italic typ
273. s 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows 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 Calling Gateway Functions to Execute Transaction Programs Table B 2 Cont Common PGAINIT and PGAINIT_SEC Parameters Parameters Type Datatypes Descriptions MODENAME IN VARCH PROFNAME IN VARCH SYNCLEVEL IN CHAR AR2 8 AR2 8 1 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 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 for this conversation This value must be either 0 or 1 SYNCLEVEL 0 indicates that the remote transaction program has no synchronization capabilit
274. s T CLIENTID char 8 NOT Specifies the name of the client ID NULL that is used by IMS Connect The default is null COMMITMODE char 1 NOT It specifies the commit mode MADE 0 the commit mode is 0 1 the commit mode is 1 The default is 1 IMSDESTID char 8 NOT Specifies the datastore names IMS NULL subsystem ID 8 bytes This parameter must be specified LTERM char 8 NOT Specifies the IMS LTERM override NULL The default is blank PG4TCPMAP Commands TCP IP Only 6 3 Before You Run the pg4tcpmap Tool Table 6 1 Cont PGA_TCP_IMSC Table Columns Column Name Type Content RACFGRPNAM char 8 NOT Specifies the RACF group name NULL The default is blank You need to specify the RACF group name if you have set PGA_SECURITY_TYPE to PROGRAM Refer to PGA_SECURITY_TYPE in Table B 1 PGA Parameters on Gateway Using TCP IP for IMS Connect in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows Refer to TCP IP Security Option SECURITY PROGRAM in Chapter 14 of the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Chapter 1
275. s Table 2 4 describes the DESCRIBE parameter Table 2 4 DESCRIBE Parameter Descriptions Parameter Description table is the tablename view is the viewname proc is the procedurename Examples DESCRIBE PROCEDURE SCOTT ADDEMP DESCRIBE SYS DUAL DESCRIBE TABLE SCOTT PERSONNEL DESCRIBE VIEW SCOTT PVIEW DESCRIBE Usage Notes You do not need to place at the end of the command Purpose Use this command to disconnect from an Oracle database Syntax The DISCONNECT command has the following syntax DISCONNECT Parameters None Procedural Gateway Administration Utility 2 13 PGAU Commands EXECUTE EXIT Examples None DISCONNECT Usage Notes mye You do not need to place at the end of the command Purpose Use this command to execute a one line PL SQL statement Syntax The EXECUTE command has the following syntax EXECUTE pl sql block Parameters pl sql blockis any valid pl sql block Refer to the Oracle Database PL SQL Language Reference for more information Examples EXECUTE balance get_balance 333 EXECUTE Usage Notes a You do not need to place at the end of the command Purpose Use this command to terminate PGAU Syntax The EXIT command has the syntax EXIT Parameters None Examples None EXIT Usage Notes a You do not need to place at the end of the command The quit command is not a valid statement in PGAU 2
276. s are filled in the enter key is pressed and several fields are returned to the user Carrying the analogy further the user might be likened to the TIP or client application a fields to be filled in are IN parameters on the TIP function call fields returned are OUT parameters on the TIP function call screen or menu is the group of IN and OUT parameters combined Client Application Development TCP IP Only 7 3 Ensuring TIP and Remote Transaction Program Correspondence a pressed enter key is likened to the PGAXFER remote procedural call RPC The actual grouping of parameters that constitute a transaction call is defined by the user The gateway places no restrictions on how a remote transaction program might correspond to a collection of TIP function calls each call having many IN and OUT parameters PGA users typically have one TIP per remote transaction program How the TIP function calls are grouped and what data parameters are exchanged on each call depends on the size complexity and behavior of the remote transaction program Refer to Oracle s Oracle Database PL SQL Language Reference for a discussion of how PL SQL packages work The following discussion covers the logic that must be performed within a TIP Refer to the sample TIP and driver supplied in the SORACLE_HOME dg4appc demo IMS directory on Microsoft Windows and in SORACLE_HOME dg4appc demo IMS directory on UNIX based systems in files pgtfli
277. s for parameters to receive but finds none and completes therefore a single TIP public function 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 TRANSACTION Correspondence The remote host transaction is defined with the PGAU DEFINE TRANSACTION statement with additional references to prior definitions of CALLs that the transaction supports You specify the remote host transaction attributes such as transaction ID or name Client Application Development TCP IP Only 7 7 Calling the TIP from the Client Application network address or location system type such as IBM370 a Oracle National Language of the remote host Note The PL SQL package name is specified when the transaction is defined this is the name by which the TIP is referenced and which the public function calls to be included within the TIP Each public function must have been previously defined with a PGAU DEFINE CALL statement which has been stored in the PG DD If you do not specify a package name TIP name in the GENERATE statement the transaction name you specified will become the package name by default In that case the transaction name tname must be unique and must be in valid PL SQL syntax within the database containing the PL SQL packages For more information refer to DEFINE TRANSACTION on page 2 10 in C
278. s share several similar parameters among themselves a RAW_TO_NUMBER a MAKE NUMBER_TO_RAW_FORMAT a MAKE RAW_TO_NUMBER_FORMAT a NUMBER_TO_RAW These similar parameters are described in detail in Table C 1 and then referenced only by name in subsequent tables listing the parameters for each UTL_PG function in this Appendix Common Input Parameters Table C 1 describes the input parameters that are common to all of the UTL_PG functions Table C 1 Input Parameters Common to UTL_PG Function Parameter Description mask is the compiler datatype mask This is the datatype to be converted specified in the source language of the named compiler compname This implies the internal format of the data as encoded according to the compiler and host platform maskopts is the compiler datatype mask options or NULL These are additional options associated with the mask as allowed or required and are specified in the source language of compname These can further qualify the type of conversion as necessary envrnmnt is the compiler environment clause or NULL These are additional options associated with the environment in which the remote data resides as allowed or required and is specified in the source language of compname This parameter typically supplies aspects of data conversion dictated by customer standards such as decimal point or currency symbols if applicable compname is the compiler name The only
279. s the last field in a COBOL definition then the COBOL program could be modified to send only the number of bytes required to satisfy the length set in the ie1d 2 field referenced by the LENGTH IS clause The LENGTH IS clause can be specified only for PIC X and PIC G fields and the picture mask for those fields cannot contain editing characters This causes conversion of exactly n instances of a set of PL SQL variables to or from a repeating group area within the remote host record the size of which area equals the group length times n repetitions PGAU generated TIPs employ PL SQL RECORDs of TABLEs to implement an array like subscript on fields within a repeating group PL SQL supports a single dimension TABLE and consequently PGAU supports only a single level of an OCCURS group Nested OCCURS groups are not supported The conversion and formatting performed are dictated by the COBOL datatype of each subfield defined within the repeating group as documented in PIC X Datatype Conversions on page D 2 and Format Conversion on page D 5 D 6 Oracle Database Gateway for APPC User s Guide Conversion Table D 4 Cont Format Conversion Descriptions Item Description OCCURS m TO n TIMES DEPENDING ON field 2 RENAMES item 2 THRU item 3 REDEFINES item 2 WHEN item 3 value This causes conversion of at least m and not over n instances of a set of PL SQL variable
280. s to or from a repeating group area within the remote host record the size of which area equals the group length times the repetition count contained in the named field PGAU generated TIPs employ PL SQL RECORDs of TABLEs to implement an array like subscript on fields within a repeating group PL SQL supports a single dimension TABLE and consequently PGAU supports only a single level of an OCCURS DEPENDING ON group Nested OCCURS DEPENDING ON groups are not supported The conversion and formatting performed are dictated by the COBOL datatype of each subfield defined within the repeating group as documented in PIC X Datatype Conversions on page D 2 and Format Conversion on page D 5 Sy Range conversion PGAU generated TIPs use a FOR LOOP algorithm with a range of 1 to whatever TIMES upper limit was specified When the TIP has been generated with the DIAGNOSE PKGEX DC option the PL SQL FOR statement which iterates an OCCURS DEPENDING ON repeating group is preceded by an IF test to ensure at TIP runtime that the DEPENDING ON field contains a number which lies within the specified range for which the lower limit need not be 1 An exception is raised if this test fails A single PL SQL variable declaration corresponds to a RENAMES definition If all the subfields covered by a RENAMES definition are PIC X then the PL SQL variable is a VARCHAR2 Otherwise any non PIC X subfield causes the PL SQL variable
281. s_attr attr at field attribute pga_data_values attr pga dtattseq id pga_data_attr attr e environment pga_environments env pga envrseg 1 compiler language pga_compilers comp pga compseq These ID numbers can be used to associate the conversions performed in the TIP with the definitions stored in the PG DD T The PG DD diagnostic references appear in TIPs generated with the PKGEX DR option as single line Comments PG DD type idno nnn The PG DD diagnostic references appear in REPORT with DEBUG listings before or to the right of their related definition entry as end delimited Comments idno nnn Refer to Appendix A Database Gateway for APPC Data Dictionary for more information about PG DD including a complete list of dictionary tables Problem Analysis with PG DD Diagnostic References TIPs should be generated by the PGAU GENERATE command with the PKGEX DR diagnostic option to include PG DD reference Comments in the TIP These diagnostic references are Comments only and do not affect the runtime overhead of the TIP Refer to Section GENERATE on page 2 15 in Chapter 2 Procedural Gateway Administration Utility for a description of the PKGEX DR parameter 1 Before defining the PL SQL package identify the transaction name ID number t and version v from the TIP specification within the TIP 2 Invoke PGAU REPORT WITH DEBUG specifying t
282. se requirements are not met attempting to use an application with a commit confirm gateway will produce unpredictable results The first thing that must be done by an OLTP transaction invoked by a commit confirm gateway is to receive the Oracle Global Transaction ID from the gateway and log it into the OLTP commit confirm transaction log database This must be done before the normal data flow between the OLTP transaction and the Oracle application begins The gateway always sends the Oracle Global Transaction ID as the very first data item If the OLTP transaction is a one shot transaction this is the only change needed If the transaction is a persistent transaction that performs more than one unit of work issues more than one commit or rollback then a new Oracle Global Transaction ID must be received and logged after every COMMIT or ROLLBACK The Oracle Global Transaction ID is sent by the gateway in a variable length record with a maximum length of 202 bytes The first 32 bytes contain a special binary string used to verify that the data came from the gateway and not from some other application The next 1 byte is a reserved field The Oracle Global Transaction ID is next with a maximum length of 169 bytes You must log the reserved field and the Oracle Global Transaction ID as well as a date time stamp and any other information you wish to log Note that the Oracle Global Transaction ID must be the key field for the log databas
283. se_ specification string PGAU gt pgtflip ctl Step 3 Execute the specification files Running the specification files will create the PL SQL stored procedures Note that the header specification file for example pgt flip pkh must be run first For Microsoft Windows C gt sqlplus userid password database_specification_string SQL gt pgtflip pkh SQL gt pgtflip pkb For UNIX based systems sqlplus userid password database_specification_string SQL gt pgtflip pkh SQL gt pgtflip pkb Step 4 Create a driver procedure to run the TIP The TIP is now ready for use For convenience it will usually be called using a driver procedure for example pgt lipd This driver will then call the individual stored procedures in the correct order Create the driver procedure and runit For Microsoft Windows C gt sqlplus lt userid gt lt password gt lt database_specification string gt SQL gt pgtflip sql SQL gt execute pgtflipd hello For UNIX based system sqlplus lt userid gt lt password gt lt database_specification string gt SQL gt pgtflip sql SQL gt execute pgtflipd hello Introduction to Oracle Database Gateway for APPC 1 19 Overview of a Gateway Using TCP IP 1 20 Oracle Database Gateway for APPC User s Guide 2 Procedural Gateway Administration Utility The Procedural Gateway Administration Utility PGAU is a utility that assists the PGA administrator or user to def
284. seesecseseeeceesesesssseecsenseececseseseaeasseseeaeesecaeees A 1 Environment Dictionary Sequence Numbers ccoooccccncncnonononcnnnnnncnononononninonnoronnn cano nono rnn corona rannnons A 1 Environment Dictionary Tables cece itaas essa aea istae sai haisi sae beri aiaa aaa A 2 A NN A 2 AAN AAA ETT E A 2 PRAVIA AAA TALA ais A 3 Pearenv Val iii aid dao ib A 3 paga compl uni dai A 3 pgardatat pesticida lead cool at ROR ee ate Ate ae A 4 peardatatyperatid aia aaa E ist soci pio A 4 pga dat type Valls ii A A dd A dat A 4 PERAL Ei E In EA LEA dd de Seach desta etn DS A EN AAA AA A 5 PEALMOTAES cin a A as A 5 PG DD Active DictONalY oviedo atea Aza ASE Conia A 5 Active Dictionary Versioning ccceccsseseesessseessseseeecsssesescsseecessesesensessscsssecesecseseceesesesenssessesseeneees A 6 Active Dictionary Sequence Numbers ccoococinnnnnnnoncnnnnnnnnonnnononononcnnnoronon nano nn coran cn cnn raro rnn ciar rnnni ns A 6 Active Dictionary Tables coimas ia uiii A 6 PLA AOS merda dr Ln rave ic bend A 6 PRactranis AD A AS TA A AAA A 7 pea trans vales ir li dia A 8 PERIS A ia A 9 pearl ad E T A 9 pga call PUMA dt A E AA nabo A 10 pa dataren iao caia A 11 pea fields Ea a R R Ea A 12 pea data cat ii died doo litte tenida A 13 peardata values cita A A T E sues escntanstesseet r e A a ES A 14 vii viii Gateway RPC Interface Calling Gateway Functions to Execute Transaction Programs oonnncinnnicnninninninnonncaninonanan aca teens B 1
285. sends the output back to the gateway 5 Finally the gateway will send the output back to the PL SQL stored procedure in the Oracle database The result is displayed in SQL Plus Congratulations PL SQL procedure successfully completed Figure 14 Communication Between Oracle Database and Mainframe Using TCP IP illustrates the communications process described in the previous Steps 1 through 5 1 16 Oracle Database Gateway for APPC User s Guide Overview of a Gateway Using TCP IP Figure 1 4 Communication Between Oracle Database and Mainframe Using TCP IP o Operating System lt gt gt Oracle Database 1 SQL gt execute pgaims snoitalutargnoC t i Congratulations PL SQL procedure successfully completed am i Client gt i PGA_TCP_IMSC i ah an roe Gateway 2 3 PGAINIT PGA PGAXFERO PGA i pr PGATERM PGA i TCP IP 3 i Mainframe psss ora tong Be ee ome eon ea Bo eae i IMS Connect 4 IMS i FLIP lt i Writing TIPs to Generate PL SQL Programs Using TCP IP Most transactions are much larger and more complex than the sample pgaims sql file referred to in Figure 1 4 Communication Between Oracle Database and Mainframe Using TCP IP Additionally communication with a normal si
286. sing the TIP initialization function The TIP directs the gateway server to initialize a conversation with the desired RHT specifying either default RHT identifying parameters supplied when the RHT was defined in the PG DD and encoded within the TIP when it was generated or override RHT identifying parameters supplied by the user or client application when the TIP initialization function is called Refer to Initializing the Conversation on page 4 16 and Overriding TIP Initializations on page 4 17 for more details Repetitively exchange data with RHT using the TIP user function s Remote host transactions that provide or require ongoing or repetitive control sequences should be controlled by the client application in the same manner that the RHT would be operated by an interactive user or other control program The intercession of the TIP and gateway server does not alter the RHT behavior instead it extends control of that behavior to the client application using the various function calls defined in the TIP A persistent RHT can be controlled with one or more TIP function calls The RHT might be designed for example to loop and return output for every input until the conversation is explicitly terminated Or it could have been designed to accept as input a count or list of operations to perform and return the results in multiple exchanges for which the TIP function has only OUT parameters A persistent RHT can also be interactive each o
287. specifying a command string on the command line using the following syntax For Microsoft Windows C gt pgau command_file C gt pgau command command_file C gt pgau command command_file For UNIX based systems pgau command_file pgau command command_file pgau command command_file The default extension is sql Use the last form if the command filename contains non alphanumeric characters To perform PG DD maintenance and PL SQL package generation you must connect to the Oracle database from PGAU as user PGAADMIN using the CONNECT command The PGAU Commands section on page 2 6 discusses how to use the CONNECT command Definitions and Generation in PGAU This version of PGAU supports the definition of remote transaction data in COBOL entered interactively or in a file File input is supported for the DEFINE and REDEFINE DATA commands and standard COBOL data division macros or copybooks can be supplied PGAU and the PG DD support different versions of user data and remote transaction definitions This facilitates alteration and testing of data formats and transactions without affecting production usage Multiple versions of any data or transaction definitions might exist You must ensure that versions stored and used in the PG DD are synchronized with the remote Procedural Gateway Administration Utility 2 3 Process to Define and Test a TIP transactions Neither the
288. stem If it is on a different system then Oracle Net is required on both systems Refer to Figure 1 2 Gateway Architecture Featuring SNA or TCP IP Protocol for a view of the gateway architecture OLTP Online Transaction Processor OLTP is any of a number of online transaction processors available from other vendors including CICS Transaction Server for z OS and IMS TM Note When your communications protocol is TCP IP only IMS is supported as the OLTP PGAU Procedural Gateway Administration Utility PGAU is the tool that is used to define and generate PL SQL transaction interface packages TIPs Refer to Chapter 2 Procedural Gateway Administration Utility in this guide for more information about PGAU PG DD Procedural Gateway Data Dictionary This component of the gateway is a repository of remote host transaction definitions and data definitions PGAU accesses definitions in the PG DD when generating TIPs The PG DD has datatype dependencies because it supports the PGAU and is not intended to be directly accessed by the customer Refer to Appendix A Database Gateway for APPC Data Dictionary in this guide for a list of PG DD tables RPC Remote Procedural Call RPC is a programming call that executes program logic on one system in response to a request from another system Refer to Gateway Remote Procedure in Appendix C of the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5
289. supported value is IBMVSCOBOLII compopts is the compiler options or NULL nlslang is the zoned decimal code page specified in Globalization Support format language_territory charset This defaults to AMERICAN_AMERICA WE8EBCDIC37C wind is the warning indicator A Boolean indicator which controls whether conversion warning messages are to be returned in the wmsgblk OUT parameter wmsgbsiz is the warning message block declared size in bytes Itis a BINARY_INTEGER set to the byte length of wmsgb1k The warning message block must be at least 512 and not more than 8192 bytes in length When declaring wmsgb1k plan on approximately 512 bytes for each warning returned depending on the nature of the requested conversion Common Output Parameter Table C 2 describes the output parameter that is common to the UTL_PG functions C 2 Oracle Database Gateway for APPC User s Guide UTL_PG Functions Table C 2 Output Parameters Common to UTL_PG Functions Parameter Description wmsgblk is the warning message block Itis a RAW value which can contain multiple warnings in both full message and substituted parameter formats if wind is TRUE This parameter should be passed to the WMSGCNT function to test if warnings were issued and to WMSG to extract any warning that are present If wind is TRUE and no warnings are issued or if wind is FALSE the length of wmsgb1k is 0 This parameter does not need to be reset before
290. t sqlplus tip_ownerYpw database_specification string SQL gt grant execute on tipname to PUBLIC For UNIX based systems sqlplus tip_owner pw database_specification string SQL gt grant execute on tipname to PUBLIC 4 28 Oracle Database Gateway for APPC User s Guide 9 Implementing Commit Confirm SNA Only Commit confirm allows the updating of local Oracle resources to occur in the same Oracle transaction as the updating of non Oracle resources accessed through the Oracle Database Gateway for APPC Read this chapter to familiarize yourself with the elements and functions of commit confirm You will find instructions for configuring gateway components for commit confirm on an SNA environment in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows Refer to Chapter 5 Configuring Your Network and Chapter 6 Gateway Configuration Using the SNA Communications Protocol of the installation and configuration guides for specific information This chapter includes the following sections Overview of Commit Confirm on page 5 1 Supported OLTPs on page 5 2 Components Required to Support Commit Confirm on page 5 2 Application Design Requirements on page 5 4 a Commit Confirm Archi
291. t application calls the TIP termination function as if it were any local PL SQL function For example term 1 indicate term called rc pgtflip pgtflip_term trannum 0 terminate normally 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 Client Application Development TCP IP Only 7 13 Calling PG4TCPMAP Error Handling The client application should include an exception handler that can clean up any active TCP IP conversations before the client application terminates The sample client application provided in pgt lipd sql1 contains an example of exception handling Gateway exceptions are reported in the range PGA 20900 to PGA 20999 and PGA 22000 to PGA 22099 When an exception occurs the TIP termination function should be called for any active conversations that have been started by prior calls to the TIP initialization function For example EXCEPTION WHEN OTHERS THEN IF term 0 THEN terminate function not called yet rc pgtflip pgtflip_term trannum 1 terminate abnormally END IF RAISE The remote transaction should also include provisions for error handling and debugging such as writing debugging information to the IMS temporary storage queue area Refer to the Oracle Database PL SQL Language Reference for a discussion
292. t been generated for the RHT being accessed refer to Chapter 3 Creating a TIP and DATA Correspondence on page 4 10 CALL Correspondence on page 4 11 and TRANSACTION Correspondence on page 4 13 for more information It is preferable to define and generate the TIP first however so that the client application reference documentation is available to you when needed Ensuring TIP and Remote Transaction Program Correspondence A remote host transaction program and its related TIP with client application must correspond on two key requirements Parameter datatype conversion which results from the way in which transaction DATA is defined Refer to Appendix D Datatype Conversions for a discussion of how PGAU generated TIPs convert data based on the data definitions APPC send receive synchronization which results from the way in which transaction CALLs are defined These DATA and CALL definitions are then included by reference in a TRANSACTION definition DATA Correspondence Using data definitions programmed in the language of the remote host transaction the PGAU DEFINE DATA command stores in the PG DD the information needed for PGAU GENERATE to create the TIP function logic to perform all data conversion from PL SQL IN parameters supplied by the receiving remote host transaction all buffering into the format expected by the receiving remote host transaction all data unbuffering from the format
293. ta STL Select Transaction latest version STV Select Transaction specific version STC Select Transaction Calls SPD Select Parameter Data SF Select Fields SFA Select Field Attributes SXF Select conversion Formats SXA Select Attribute conversions The SQL Plus test scripts in Table 8 3 are provided to perform the identical SELECTS as GENERATE performs to determine which PG DD rows are being used when the TIP E dg4appc admin is generated These files are loaded into the 3ORACLE_HOM directory on Microsoft Windows or into the SORACLE_HOM E dg4appc admin directory on UNIX based systems during installation Troubleshooting 8 3 Data Conversion Errors Table 8 3 SQL Plus Test Scripts and Their Corresponding Entries Script Entry pgddsed sql Select Environment Data pgddstl sql Select Transaction latest version pgddstv sql Select Transaction specific version pgddstc sql Select Transaction Calls pgddspd sql Select Parameter Data pgddsf sql Select Fields pgddsfa sql Select Field Attributes pgddsxf sql Select Conversion Formats pgddsxa sql Select Attribute conversions The scripts are shown in the same order used by GENERATE and each script prompts the SOL Plus user for the required input The information retrieved from a previous select is often used as input to a subsequent select If a you suspect that a PG DD field entry has produced inaccurate data browse the sql files liste
294. taining such REDEFINE clauses get unpredictable results The PG DD and TIPs generated by PGAU support COBOL specified as IBMVSCOBOLII when defining data When USAGE PASS has been specified on the PGAU DEFINE DATA statement the following datatype and format conversions are supported m PIC X PIC G PIC X Datatype Conversions PGAU TIPs convert the COBOL x datatype to a PL SQL CHAR datatype of the same character length Globalization Support character set translation is also performed Note COBOL lacks a datatype specifically designated for variable length data It is represented in COBOL as a subgroup containing a PIC 9 length field followed by a PIC X character field For example 10 NAME 5 LENGTH PIC S9 4 5 LETTERS PIC X 30 Given this context it cannot be guaranteed that all instances of an S9 4 field followed by an X field are always variable length data Rather than PGAU TIPs converting the above COBOL group NAME to a VARCHAR the TIPs instead construct a nested PL SOL record as follows TYPE NAME_typ is RECORD LENGTH NUMBER 4 0 LETTERS CHAR 30 D 2 Oracle Database Gateway for APPC User s Guide Conversion TYPE is RECORD NAME NAME_typ It is the client application s responsibility based upon specific knowledge of the remote host data to extract NAME LENGTH characters from NAME LETTERS and assign the result to
295. te value charval varchar2 40 Character attribute value dateval date Date attribute value pga_usage The pga_usage table performs a referential integrity check of pga_data and pga_ field column usage as presented in Table A 10 Table A 10 pga_usage Column Type Content name varchar2 6 pga_modes Value for the usage field of data dictionary tables For example PASS SKIP NULL ASIS Primary key Max length gt 4 char string length The pga_modes table performs a referential integrity check of pga_call_parm column mode as presented in Table A 11 Table A 11 pga_modes Column Type Content name varchar2 6 Name of valid parameter call modes For example IN OUT IN OUT PG DD Active Dictionary Max length gt IN OUT string length The PG DD active data dictionary is created by pgddcr8 sal at installation but maintained using PGAU The active dictionary can refer to items by ID number in the environment dictionary Database Gateway for APPC Data Dictionary A 5 PG DD Active Dictionary Active Dictionary Versioning The PG DD active dictionary tables contain the descriptions of transactions and data structures There might be more than one version of a definition Old versions are retained indefinitely In PGAU dictionary operations a definition is referred to by its name which can be qualified by a specific version number If omitted the most recent ve
296. tecture on page 5 4 a Commit Confirm Flow on page 5 5 Overview of Commit Confirm Important If you are planning to implement commit confirm then you should already have configured the components Depending on your platform refer to Chapter 12 of the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Chapter 9 of the Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows for instructions on its configuration Commit confirm is a special implementation of two phase commit that allows a database or gateway that does not support full two phase commit to participate in distributed update transactions with other databases or gateways that do support full Implementing Commit Confirm SNA Only 5 1 Supported OLTPs two phase commit In this implementation the commit confirm site is always the first to be committed after all other sites have been prepared This allows all sites to be kept in sync because if the commit confirm site fails to commit successfully all other sites can be rolled back Within an Oracle distributed transaction all work associated with that transaction is assigned a common identifier known as the Oracle Global Transaction ID This identifier is guaranteed to be unique so that it can be used to exclusively identify a partic
297. teway Server Tracing The gateway contains extensive tracing logic in the gateway remote procedural calls RPCs and the APPC specific code Tracing is enabled through gateway initialization parameters or dynamic RPC calls to the gateway The trace provides information about the execution of the gateway RPC functions and about the execution of the APPC interface The trace file contains a text stream written in chronological sequence of events The trace is designed to assist application programmers with the debugging of their OLTP transaction programs and Oracle applications that communicate with those transaction programs through the gateway A single trace file is created for an entire gateway session from the time the database link is opened until it is closed The trace can be directed to a specific path filename or to a path directory only In the first case the file is overwritten each time a new session begins for the gateway being traced When the trace target is a directory a separate file with a generated name containing the operating system process ID is written for each gateway session The latter approach must be used whenever the gateway to be traced might be the target of new sessions after the desired trace is written but before it can be copied and saved Conversely in some situations you might choose to create a distinct gateway system identifier used solely for tracing and direct its trace to a single specific filename This a
298. the EXECUTE or PRINT command or for use with a PL SQL block Syntax The VARIABLE command has the syntax VARIABLE name type Parameters Table 2 13 describes the VARIABLE parameters Table 2 13 VARIABLE Parameter Descriptions Parameter Description name Is a variable name type Is the variable datatype Examples VARIABLE balance NUMBER VARIABLE emp_name VARCHAR2 VARIABLE Usage Notes a You do not need to place at the end of the command Procedural Gateway Administration Utility 2 31 PGAU Commands 2 32 Oracle Database Gateway for APPC User s Guide 3 Creating a TIP This chapter shows in detail how you can define generate and compile a Transaction Interface Package TIP It assumes that a remote host transaction program RTP already exists This transaction program has operational characteristics that dictate how the TIP is defined and how the TIP is used by the client application This chapter contains the following sections Granting Privileges for TIP Creators on page 3 1 Evaluating the RHT on page 3 2 Defining and Generating the TIP on page 3 6 a Compiling the TIP on page 3 7 TIP Content Documentation tipname doc on page 3 8 The following steps create a TIP for use with a remote host transaction RHT a evaluating the RHT preparing the PGAU statements a defining and generating the TIP compiling the TIP This chapter also
299. the TYPE tran_rectype is RECORD statement Refer to the tipname doc content file for a complete description of the user declarations you can reference The client application calls the TIP public function as if it were any local PL SQL function rc tip_calll tranuse appl_var appl_record In the CICS DB2 inquiry example the PL SQL driver pgadb2id sql which is located in SORACLE_HOME dg4appc demo CICcs directory for Microsoft Windows Client Application Development SNA Only 4 15 Calling the TIP from the Client Application and SORACLE_HOME dg4appc demo CICS directory for UNIX based systems is the client application and includes the following declaration CREATE or REPLACE PROCEDURE db2idriv empno IN CHAR IS tranuse INTEGER 0 transaction usage number DCLEMP PGADB21 DCLEMP_typ DB2 EMP row definition DB2 PGADB21 DB2_typ DB2 diagnostic information rc INTEGER 0 PGA RPC return codes E line VARCHAR2 132 work buffer for output el term INTEGER 0 1 1f pgadb21_term called ET Initializing the Conversation The call to initialize the conversation serves several purposes To cause the PL SQL package the TIP to be loaded and to perform the initialization logic programmed in the TIP initialization section To cause the TIP init function to call the PGAINIT remote procedural call RPC which in turn establishes communication with the remote transaction program RTP
300. the end of the command Procedural Gateway Administration Utility 2 23 PGAU Commands REPORT Purpose This command produces a report of selected data from the PG Data Dictionary Selection criteria might determine that a single TRANSACT is reported or that all TRANSACTI LO LON CALL or 1 DATA entity with or without an explicit version N CA L Or DATA entities with a given name be reported or that all entities in the PG DD be reported or that all invalid TRANSACTI entities be reported Syntax REPORT TRANSACTION tname CALL cname DATA dname VERSION ver1 ALL TRANSAC WITH CALLS ISOLATED Parameters Table 2 7 describes the R1 LONS or CALLs and all unreferenced CALLS or DATA TIONS tname CALLS cname DATA dname DATA DEBUG EPORT parameter Table 2 7 REPORT Parameters Descriptions Parameter Description TRAN SACTION tname CALL cname DATA dname VERSION verl ver2 13 ALL TRANSACTIONS tname ALL CALLS cname WITH WITH WITH 1 DATA dname CALLS DATA DI EBUG Reports the PG DD contents for the latest or selected versions of the transaction tname Reports the PG DD contents for the latest or selected versions of the call cname Reports the PG DD contents for the latest or selected versions of the data dname Reports selected versions of th
301. the individual stored procedures in the correct order Create the driver procedure and run it For Microsoft Windows C gt sqlplus lt userid gt lt password gt lt database_specification string gt SQL gt pgadb2id sql SQL gt execute db2idriv 000320 For UNIX based systems sqlplus lt userid gt lt password gt lt database_specification string gt SQL gt pgadb2id sql SQL gt execute db2idriv 000320 Overview of a Gateway Using TCP IP If you are using the TCP IP communication protocol read the following sections to develop an understanding of how the gateway communicates with the Oracle database and with the mainframe as well as transaction types unique to your gateway and writing TIPs Transaction Types for a Gateway Using TCP IP The Oracle Database Gateway for APPC using TCP IP support for IMS Connect supports three types of transaction socket connections transaction socket The socket connection lasts across a single transaction persistent socket The socket connection lasts across multiple transactions nonpersistent socket The socket connection lasts across a single exchange consisting of one input and one output Note Do not use the nonpersistent socket type if you plan to implement conversational transactions because multiple connections and disconnections will occur Refer to the section about pg4tcpmap commands in Chapter 6 PG4TCPMAP Commands TCP IP Only of this guide
302. these positions contain blank in the character set specified for the remote host what data is actually present is the user s responsibility PIC GGBGGG Is a DBCS field 12 bytes in length and would be converted in a single UTL_RAW CONVERT call No testing or translation is done on the contents of the byte positions indicated by B While COBOL language rules indicate that these positions contain blank in the character set specified for the remote host what data is actually present is the user s responsibility PIC 9 PGAU TIPs convert the COBOL 9 datatype to a PL SQL NUMBER datatype of the same precision and scale Globalization Support character set translation is also performed on signs currency symbols and spaces The following are supported m COMPUTATIONAL binary COMPUTATIONAL 3 packed decimal COMPUTATIONAL 4 binary DISPLAY zoned decimal For DISPLAY datatypes the following sign specifications are supported m SEPARATE CHARACTER m LEADING m TRAILING Refer to NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values in Appendix C The UTL_PG Interface for more information about numeric datatype conversions COMPUTATIONAL 1 and COMPUTATIONAL 2 floating point datatypes are not supported D 4 Oracle Database Gateway for APPC User s Guide Conversion Table D 3 Cont COBOL PGAU Conversion COBOL Datatype Description of Conversion by PGAU FILLER
303. ticipate in APPC conversation sharing The tranuse values are incompatible between pre 3 4 0 and 3 4 0 or later releases This should not pose a problem for you for the following reason before 3 4 0 all RHT functions defined in a TIP had to be called through that TIPs functions and the init function of that same TIP had to be called first to initialize the conversation The tranuse value was only valid for the TIP which initialized it Thus unless you make programming changes it is not possible for an existing application to accidentally mix tranuse values Pre 3 4 0 TIPs and client applications can continue to be used without change and old client applications can call new 3 4 0 or later TIPs without change This is made possible when an old TIP body is regenerated and compiled the TIP now becomes 4 22 Oracle Database Gateway for APPC User s Guide APPC Conversation Sharing capable of APPC conversation sharing even though the old client application has not changed None of the functions of a pre 3 4 0 TIP can share an APPC conversation However once a TIP is regenerated at 3 4 0 or later any of its functions can share APPC conversations APPC Conversation Sharing for TIPs That Are Too Large You can use conversation sharing to circumvent a TIP that is too large to compile This is identified by PLS 00123 package too large to compile or some other problem symptom such as PL SOL compilation hanging In this case you
304. tomatically generates equivalent PL SQL variables and records of fields or tables for the client application to reference in its calls to the generated TIP As discussed a parameter might be a simple data item such as an employee number or a complex item such as an employee record PGAU DEFINE DATA automatically extracts the datatype information it needs from the input program data definition files In this example empno and emprec are the arguments to be exchanged pgadb2i_main trannum empno emprec A PGAU DEFINE DATA statement must therefore be issued for each of these DEFINE DATA EMPNO PLSDNAME EMPNO USAGE PASS LANGUAGE IBMVSCOBOLIT 01 EMP NO PIC X 6 Je DEFINE DATA EMPREC PLSDNAME DCLEMP USAGE PASS LANGUAGE IBMVSCOBOLIT INFILE emp cob Note that a definition is not required for the trannum argument This is the APPC conversation identifier and does not require a definition in PGAU CALL Correspondence 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 TIP must also cause the gateway to issue APPC RECEIVEs when the remote transaction program issues APPC SENDs
305. ual to the count of warnings present in the RAW wmsgblk Table C 14 lists possible returned values Table C 14 WMSGCNT Return Values Description gt 0 indicates a count of warnings present in wmsgb1k 0 indicates that no warnings are present in wmsgb1k The UTL_PG Interface C 9 UTL_PG Functions WMSG Error and Warning Messages If you receive an ORA xxxx error or warning message refer to the Oracle Database Error Messages guide for an explanation and information about how to handle it WMSG extracts a warning message specified by wmsgi tem from wmsgb1k Syntax function WMSG wmsgblk IN RAW wmsgitem IN BINARY_INTEGER wmsgno OUT BINARY_INTEGER wmsgtext OUT VARCHAR2 wmsgfill OUT VARCHAR2 RETURN BINARY_INTEGER Where Table C 15 describes the parameters in this function Table C 15 WMSG Function Parameters Parameter Description wmsgblk is a RAW warning message block returned from one of the following functions m MAKE_NUMBER_TO_RAW_FORMAT m MAKE_RAW_TO_NUMBER_FORMAT m NUMBER_TO_RAW m RAW_TO_NUMBER wmsgitem is a BINARY_INTEGER value specifying which warning message to extract numbered from 0 for the first warning through n minus 1 for the nth warning wmsgno is an OUT parameter containing the BINARY_INTEGER hexadecimal value of the warning number This value after conversion to decimal is documented in the Oracle Database
306. ue area Refer to the Oracle Database PL SQL Language Reference for a discussion of how to intercept and handle Oracle exceptions Granting Execute Authority The TIP is a standard PL SQL package and execute authority must be granted to users who call the TIP from their client application In this example we grant execute on the PGADB2I package to user SCOTT GRANT EXECUTE ON PGADB2I TO SCOTT Refer to the Oracle Database Administrator s Guide for further information Executing the Application Before executing the client application ensure that a connection to the host is established and that the receiving partner is available In this example we use PL SQL driver DB2IDRIV to execute the CICS DB2 inquiry To execute this client application enter from SQL Plus set serveroutput on execute DB2IDRIV nnnnnn APPC Conversation Sharing Multiple TIPs can share the same APPC conversation with one or more Remote Host Transactions RHTs which are also sharing that same conversation Two benefits derive from this feature 4 20 Oracle Database Gateway for APPC User s Guide APPC Conversation Sharing a Existing RHTs which rely upon passing control of a conversation are supported by Oracle Database Gateway for APPC a TIPs otherwise too large for PL SQL compilation can be separated into multiple smaller TIPs each with fewer user defined functions providing the client application with the same set of function
307. ular distributed transaction The key requirement for commit confirm support is the ability for the commit confirm site in this case the Oracle Database Gateway for APPC to be able to log the Oracle Global Transaction ID as part of its unit of work so that if a failure occurs the gateway s recovery processing can determine the status of a particular Oracle Global Transaction ID by the presence or absence of a log entry for that transaction A new Oracle Global Transaction ID is generated after every commit or rollback operation The Oracle Database Gateway for APPC implements commit confirm using LU6 2 SYNCLEVEL 1 This is similar to the implementation of single site update with the added advantage that resources on both the Oracle site and the OLTP being accessed by the gateway can be updated and kept in sync The main difference is that the commit confirm implementation requires some additional programming in the OLTP transaction to perform the transaction logging necessary for recovery support Supported OLTPs Since commit confirm uses LU6 2 SYNCLEVEL 1 it can be supported by any OLTP that supports APPC including CICS Transaction Server for z OS and IMS TM The Oracle Database Gateway for APPC provides sample commit confirm applications for both CICS Transaction Server for z OS and IMS TM With CICS Transaction Server for z OS the standard command level EXEC CICS interface can be used for all APPC communications In addition the CPI
308. users actually needing the trace The second method is more flexible and allows the application programmer to selectively trace events on a single gateway session without affecting the operation of other users gateway sessions Before the gateway server trace is enabled perform the tasks listed in Defining the Gateway Trace Destination on page 8 10 Enabling the Gateway Trace Using Initialization Parameters Edit the initsid ora file and add the following line at the end of the file or if a S1 TRACE_LEVEL parameter is already specified modify it E A SET TRACE _LEVEL trace where trace is a numeric value from 1 to 255 indicating which traces are to be enabled For further information on the use of this parameter refer to PGA Troubleshooting 8 11 Gateway Server Tracing Parameters in Appendix A Gateway Initialization Parameters for SNA Protocol of the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows Once this step is completed tracing is enabled for the desired gateway system identifier Enabling the Gateway Trace Dynamically from PL SQL The following is only needed for user written TIPs PGAU generated TIPs automatically include the following facilities Refer to Controlling
309. utput being specified by a previous input selection and ending only when the conversation has been explicitly terminated by the client application The TIP function calls available to the client applications and their specific syntax is documented in the TIP Content documentation file for the specific TIP RHT The manner in which the RHT interprets the TIP IN parameters and returns TIP OUT parameters must be determined from the RHT or explained by the RHT programmer The TIP provides the function calls and the exchanged parameter datatypes to facilitate the client application s control of the RHT and imposes no limitations or preconditions on the sequence of operations the RHT is directed to perform The TIP provides the client application with the calls and data parameters the RHT was defined to accept in the PG DD a Terminate the RHT using the TIP termination function Regardless of the type of RHT being accessed the TIP terminate function should be called to clean up and terminate the conversation with the RHT Conversations with persistent RHTs can be terminated from the gateway server before the RHT terminates or the RHT might have already terminated The TIP must perform its cleanup as well and this cleanup is only performed at the termination request of the client application The client application can request a normal or an aborted termination Refer to Terminating the Conversation on page 4 19 for more information 4 8 Or
310. vant to the remote transaction 1 2 Oracle Database Gateway for APPC User s Guide Terms Terms a tool to generate the PL SQL Transaction Interface Package or TIP areport utility to view the information stored in the gateway dictionary a complete set of tracing and debugging facilities a wide set of samples to demonstrate the use of the product against datastores such as DB2 IMS and CICS Site autonomy and security The gateway provides site autonomy allowing you to do such things as authenticate users It also provides role based security compatible with any security package running on your mainframe computer Automatic conversion Through the TIP the following conversions are performed ASCII to and from EBCDIC remote transaction program datatypes to and from PL SQL datatypes national language support for many languages a Globalization Support TCP IP support for IMS Connect This release of the gateway includes TCP IP support for IMS Connect giving users a choice of whether to use an SNA or TCP IP communication protocol IMS Connect is an IBM product which allows TCP IP clients to trigger execution of IMS transactions The gateway can use a TCP IP communication protocol to access IMS Connect which triggers execution of IMS transactions There is no SNA involvement with this configuration Related to this feature of the gateway is The gateway mapping tool This release of the gateway includes a to
311. voids the problem of an ever increasing set of trace files when for example repeated attempts are necessary to reproduce or debug a problem A fixed filename should never be used if there is any chance that an unexpected gateway session could overlay a useful trace Defining the Gateway Trace Destination This section describes how to define the destination of trace files to the gateway and how to cause the gateway to create the trace files during initialization Note that this does not enable any gateway tracing it merely defines the destination of any trace output produced when the gateway tracing is enabled 1 Choose a gateway system identifier to trace Decide whether you will be tracing an existing gateway system identifier or a new one created specifically for tracing If a new system identifier will be used configure the new system identifier exactly the same as the old one by creating a new initsid ora a copy of the old entries in listener ora as necessary and a new Oracle database link Test the new system identifier to ensure it works before proceeding 8 10 Oracle Database Gateway for APPC User s Guide Gateway Server Tracing 2 For Microsoft Windows in S3ORACLE_HOME dg4appc admin edit the initsid ora file so it contains the following SET TRACE_LEVEL 255 SET LOG_DESTINATION logdest For UNIX based systems in SORACLE_HOME dg4appc admin edit the initsid ora file so it contains the foll
312. when conflicting format specifications are supplied This function returns a RAW value containing the conversion format which can be passed to UTL_PG NUMBER_TO_RAW_FORMAT The implementation length of the result format RAW is 2048 bytes For detailed information about the mask maskopts envrnmnt compname and compopts arguments refer to NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values on page C 11 Syntax function MAKE_NUMBER_TO_RAW_FORMAT mask IN VARCHAR2 maskopts IN VARCHAR2 envrnmnt IN VARCHAR2 compname IN VARCHAR2 compopts IN VARCHAR2 nlslang IN VARCHAR2 wind IN BOOLEAN wmsgbsiz IN BINARY_INTEGER wmsgblk OUT RAW RETURN RAW Where Table C 9 describes the parameters in this function Table C 9 MAKE_NUMBER_TO_RAW_FORMAT Function Parameters Parameter Description mask is the compiler datatype mask maskopts are the compiler datatype mask options or NULL envrnmnt is the compiler environment clause or NULL compname is the compiler name compopts are the compiler options or NULL nlslang is the zoned decimal code page in Globalization Support format wind is a warning indicator wmsgbsiz is the warning message block size in bytes wmsgblk is the warning message block This is an OUT parameter Defaults and Optional Parameters Table C 10 describes the defaults and optional parameters for the MAKE_NUMBER_TO_RAW_FORMAT function Table C 10 Optional Default Parameters MAKE_NUMBER_TO_RAW_
313. ws identified by dname and version are updated or replaced by the definition input REMOTE LANGUAGE and LOCAL LANGUAGE override the character sets used for conversion of any individual SBCS DBCS or MBCS character data field LANGUAGE language and definition INFILE filespec are mandatory as a group If data definitions are to be supplied then a LANGUAGE parameter must be specified and then either the inline definition or INFILE must also be specified a The presence of definition INFILE filespec denotes that multiple data fields those PG DD rows identified by dname and version are updated or 2 22 Oracle Database Gateway for APPC User s Guide PGAU Commands REM replaced by the definition input Fewer equal or greater numbers of fields might result from the replacement INFILE filespec isa platform specific designation of a disk file COMPOPTS TRUNC BIN should be used only when the remote host transaction was compiled using COBOL with the TRUNC BIN compiler option specified When this option is used binary data items defined as PIC 9 4 or PIC 9 4 can actually contain values with 5 digits and binary data items defined as PIC 9 9 or PIC S9 9 can actually contain values with 10 digits Without COMPOPTS TRUNC BIN PGAU generates NUMBER 4 0 or NUMBER 9 0 fields for these data items resulting in possible truncation of the values When
314. y netaddr VARCHAR2 255 Side Profile 7 oltpuser VARCHAR2 8 userid for OLTP access oltppass VARCHAR2 8 password for OLTP access FUNCTION pgadb2i_init init standard 4 16 Oracle Database Gateway for APPC User s Guide Calling the TIP from the Client Application tranuse IN OUT BINARY_INTEGER RETURN INTEGER FUNCTION pgadb2i_init init override tranuse IN OUT BINARY_INTEGER override IN override_Typ RETURN INTEGER FUNCTION pgadb2i_init init diagnostic tranuse IN OUT BNARY_INTEGER tipdiag IN CHAR RETURN INTEGER FUNCTION pgadb2i_init init over diag tranuse IN OUT BINARY_INTEGER override IN override_Typ tipdiag IN CHAR RETURN INTEGER Transaction Instance Parameter This transaction instance number shown in examples as tranuse must be passed to subsequent TIP exchange and terminate functions It identifies to the gateway on which APPC conversation and therefore which iteration of a remote transaction program the data is to be transmitted or communication terminated A single client application might control multiple instances of the same remote transaction program or multiple different remote transaction programs all concurrently The transaction instance number is the TIP s mechanism for routing the client application call through the gateway to the intended remote transaction program It is the responsibility of the client application to save the
315. y further the user might be likened to the TIP or client application fields to be filled in are IN parameters on the TIP function call fields returned are OUT parameters on the TIP function call screen or menu is the group of IN and OUT parameters combined a pressed enter key is likened to the PGAXFER remote procedural call RPC The actual grouping of parameters that constitute a transaction call is defined by the user The gateway places no restrictions on how a remote transaction program might correspond to a collection of TIP function calls each call having many IN and OUT parameters PGA users typically have one TIP per remote transaction program How the TIP function calls are grouped and what data parameters are exchanged on each call depends on the size complexity and behavior of the remote transaction program Refer to Oracle s Oracle Database PL SQL Language Reference for a discussion of how PL SQL packages work The following discussion covers the logic that must be performed within a TIP Refer to the sample TIP and driver supplied in the SORACLE_HOME dg4appc demo CICcs directory for Microsoft Windows or SORACLE_HOME dg4appc demo CICS directory for UNIX based systems in files pgadb2i pkh pgadb2i pkb and pgadb2id sql Remote Host Transaction Types From a database gateway application perspective there are three main types of remote host transactions one shot persistent a mult
316. y is using SNA Refer to Chapter 4 Client Application Development SNA Only for more information If your gateway is using TCP IP support for IMS Connect Refer to Chapter 7 Client Application Development TCP IP Only for more information Compiling the TIP Exit PGAU Remain in your current directory and invoke SQL Plus For Microsoft Windows C gt sqlplus userid pw database_specification_string SQL gt set echo on SQL gt pgau pkh SQL gt pgau pkb For UNIX based systems sqlplus userid pw database_specification_string SQL gt set echo on SQL gt pgau pkh SQL gt pgau pkb The last two commands compile the TIP specification and body respectively You have now compiled a TIP which can be called by your client application If your client application is already written you can begin testing For more information about designing your client application and compiling a TIP refer to Chapter 1 Introduction to Oracle Database Gateway for APPC and Appendix E Tip Internals If your gateway is using SNA Refer to Chapter 4 Client Application Development SNA Only for information about PGAU statement syntax and usage Creating a TIP 3 7 TIP Content Documentation tipname doc If your gateway is using TCP IP support for IMS Connect Refer to Chapter 7 Client Application Development TCP IP Only for information about PGAU statement syntax and usage TIP Content Documentation tipname doc
317. ying the user ID and password in addition to the Oracle instance The CONNECT command has the following syntax Syntax For Microsoft Windows CONNECT username username password username connect string username password connect string For UNIX based systems CONNECT username username password username connect string username password connect string Parameters username password for Microsoft Windows and username password for UNIX based systems are the usernames and passwords used to connect to PGAU and connect string specifies the service name of the remote database Refer to the Oracle Database Net Services Administrator s Guide Services Administrator s Guide for more information about specifying remote databases Examples CONNECT CONNECT SCOTT TIGER CONNECT SCOTT OTHERSYS CONNECT Usage Notes Before connecting you must set ORACLE_SID to the database SIDname a Ifyou want to connect to a remote database you must set TNS_ADMIN to the full pathname of the directory in which the file tnsnames ora is stored You do not need to place a semi colon at the end of the command 2 6 Oracle Database Gateway for APPC User s Guide PGAU Commands DEFINE CALL Purpose This command creates a new version of the PL SOL call definition in the PG Data Dictionary Syntax DEFINE CALL cname PKGCALL pcname PARMS dname IN OUT IN OUT VERSion datavers W
318. yntax function NUMBER_TO_RAW n IN NUMBER mask IN VARCHAR2 maskopts IN VARCHAR2 envrnmnt IN VARCHAR2 compname IN VARCHAR2 compopts IN VARCHAR2 nlslang IN VARCHAR2 wind IN BOOLEAN wmsgbsiz IN BINARY_INTEGER wmsgblk OUT RAW RETURN RAW Where Table C 5 describes the parameters in this function C 4 Oracle Database Gateway for APPC User s Guide UTL_PG Functions Table C 5 NUMBER_TO_RAW Function Parameters Parameter Description n is the Oracle number to be converted mask is the compiler datatype mask maskopts are the compiler datatype mask options or NULL envrnmnt is the compiler environment clause or NULL compname is the compiler name compopts are the compiler options or NULL nlslang is the zoned decimal code page in Globalization Support format wind is a warning indicator wmsgbsiz is the warning message block size in bytes wmsgblk is the warning message block This is an OUT parameter Defaults and Optional Parameters Table C 6 describes the defaults and optional parameters for the NUMBER_TO_RAW function Table C 6 Defaults and Optional Parameters for NUMBER_TO_RAW Function Parameter Description maskopts null allowed no default value envrnmnt null allowed no default value compopts null allowed no default value Return Value A RAW value corresponding in value to n Error and Warning Messages If you receive an ORA xxxx error or warning message refe
319. you have identified the remote host transaction program facilities to be called 3 Move relevant COBOL records layout copybooks to the gateway system for input to PGAU 4 Describe the remote host transaction data and calls to the PG Data Dictionary PG DD with DEFINE DATA DEFINE CALL and DEFINE TRANSACTION statements 5 Generate the TIP in the Oracle database using GENERATE 6 Create the client application that calls the TIP public functions 7 Grant privileges on the newly created package TIP Content and Purpose The content of a PGAU generated TIP reflects the calls available to the remote host transaction and the data that has been exchanged Understanding this content helps when designing and debugging client applications that call the TIP A TIP is a PL SQL package and accordingly has two sections 1 A Package Specification containing a Public function prototypes and parameters and 2 A Package Body containing a Private functions and internal control variables Public functions Package initialization following the last public function The purpose of the TIP is to provide a PL SQL callable public function for every allowed remote transaction program interaction A remote transaction program interaction is a logically related group of data exchanges through one or more PGAXFER RPC calls This is conceptually similar to a screen or menu interaction in which several field
320. your gateway is using the TCP IP communication protocol this guide uses an IMS inquiry as an example Transaction Interface Packages TIPs pgt lip pkh and pgtflip pkb send input to IMS through IMS Connect and receive the flipped input as the output 1 6 Oracle Database Gateway for APPC User s Guide Architecture of the Gateway The IMS inquiry sample FLIP and its associated PGAU commands are located in the SORACLE_HOME dg4appc demo IMS directory for Windows and ORACLE_ HOME dg4appc demo IMS directory for UNIX The sample IMS inquiry used as an example for a gateway using TCP IP is located in files pgt 1ip pkh and pgtflip pkb Refer to the README doc file for more information about installing and using other IMS samples It can be found in the 3ORACLE_HOME dg4appc demo IMS directory for Windows and SORACLE_HOME dg4appc demo IMS directory for UNIX Architecture of the Gateway The architecture of Oracle Database Gateway for APPC consists of several components 1 Oracle database Refer to the configuration chapter corresponding to your communications protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for AIX 5L Based Systems 64 Bit HP UX Itanium Solaris Operating System SPARC 64 Bit Linux x86 and Linux x86 64 or Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windowsfor a description of the various methods for establishi
321. ze for a single gateway send whichis 32 763 bytes for a mapped gateway conversation 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 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 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 Calling Gateway Functions to Execute Transaction Programs PGATERM Table B 4 Cont PGAXFER Parameters Parameter Type Datatype Description RECVBUFL IN RECVLNS INOUT BINARY_INT RAW 1024 EG ER 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 Buffer containing an array of up to 256 4 byte intege
322. zed RTP remote transaction program would require you to create an extremely long PL SQL file Oracle Database Gateway for APPC s TIP function generates the PL SQL procedure for you The following is a brief description of the four steps necessary for you to generate a TIP Refer to Chapter 3 Creating a TIP for detailed information about this procedure and refer to Chapter 2 Procedural Gateway Administration Utility for more information about PGAU All parameter names in this section are taken froma file called pgtflip ctlinthe SORACLE_HOME pga4appc demo IMS directory on Microsoft Windows or SORACLE_HOME pga4appc demo IMS directory on UNIX based systems Steps to Writing a TIP on a Gateway Using TCP IP Follow these steps to write a TIP Step 1 Create a control file The user writes the control files The control file has four main types of PGAU commands Introduction to Oracle Database Gateway for APPC 1 17 Overview of a Gateway Using TCP IP 1 DEFINE DATA This is used to define input and output fields using COBOL data definitions Sample define data define data flipin plsdname flipin usage pass language ibmvscobolii 01 msgin pic x 20 define data flipout plsdname flipout usage pass language ibmvscobolii 01 msgout pic x 20 2 DEFINE CALL This is used to define PL SQL functions calls to be generated as part of the package a Sample define call define call

Download Pdf Manuals

Related Search

Related Contents

Uniross SB Li-Ion Charger Universal  American Standard 2996C203.020 Installation Guide  Manhattan USB to ExpressCard Adapter  Epson PowerLite 1220  macVCR Manual - Arten Science Limited  MSI Workstation WT70 2OK-2452XES  A1. Espace d`administration et configuration de Cart@DS CS  2 GRAND ANGLE - Viande séchée du Valais  Les loisirs  

Copyright © All rights reserved. Failed to retrieve file