| Oracle Procedural Gateway for APPC (PG4APPC) |
|
||||||
The Oracle Procedural Gateway for APPC permits an Oracle application to execute a mainframe IMS transaction.
Oracle Procedural Gateway for APPC (PG4APPC) allows an Oracle application
program running on a UNIX server to execute mainframe IMS transactions
via Remote Procedure Calls (RPCs). The RPCs convert parameters and
data into an IMS transaction input string which is then sent to the mainframe
via "Advanced Program-to-Program Communication" (APPC) calls and executed
in IMS. The output
from the transaction is returned to the caller. The IMS transaction
can include access to data from IMS DLI files and/or DB2 tables for read
or update, or any other function which can be performed by an IMS transaction,
except screen input/output. PG4IMS runs on the UW Production Application
Server (UWP1) but the RPCs can be called from any Oracle server via Oracle
database links.
Developing Applications with the Procedural Gateway
Creating the Transaction
The Procedural Gateway runs a mainframe IMS/TM non-conversational transaction.
Developing the transaction is work done by Applications Technology programmer.
The AT developer should notify the DRMT contact early on of plans to use
the gateway so that DRMT will have time to do its part.
If the transaction is new, it must be defined in IMS using standard procedures (TP PSB Request Form). The AT developer can request both test and production transactions be included in the next IMS GEN. (Contact Bill Lehman, DRMT, for GEN instructions.) Prior to the GEN, the developer can request System Operations to specially start the transaction for 7AM to 7PM, M-F, availability. Having the transaction “up” will avoid at least one common source of errors during the testing cycle.
PG4APPC does not support IMS formatted screens, so existing transactions which use IMS Message Format Services (MFS) to format input and output data for screen display will not execute from the Procedural Gateway. Input to and output from the IMS transaction must be in the form of unformatted data strings. Use the format-name ‘DFS.EDTN’ when writing output in the UWDCIO call. This tells IMS to bypass MFS.
In designing the input and output strings, try to use fixed-length character datatypes for all fields, leaving any necessary data conversions (to numeric or date, for example) within the Oracle PL/SQL environment. If possible, use a single, common definition for input and output, embedding a “call-type” field if the IMS transaction performs more than one type of behavior.
Note again that the IMS transaction must be non-conversational. It cannot write to a Scratch Pad Area (SPA).
The transaction should undergo significant functional testing by AT before any attempt is made to call it via the Procedural Gateway. For testing purposes, the transaction may need to be compiled as a subroutine and temporarily linked into a stub driver program. When adequate mainframe testing is complete, an Oracle “TIP” can be created.
Creating the TIP
The IMS transaction must be called from a particular kind of Oracle PL/SQL package called a “TIP” (Transaction Interface Program). TIPs are generated using a Procedural Gateway utility program. The generated TIP code implements the necessary UNIX-to-mainframe communications calls using the IBM APPC protocol. TIPs are large, ugly, and cannot be modified except through the utility provided.
TIPs are generated by DRMT. Both test and production TIPs reside within UWP1 on Humvee/Ziggy. The runtime data dictionary for the Procedural Gateway (actually just a set of 20 Oracle tables) also exists within UWP1.
In order to generate the TIP, the AT developer must supply a precise definition for each possible type of call to the IMS transaction, plus precise layouts of the input and output strings used in each call.
By DoIT convention, the name of the TIP will be the name of the production IMS transaction. DRMT will ensure that calls initiated from test Oracle execute the IMS test transaction (Zxxxx) and that calls executed from production Oracle execute the production IMS transaction. Test systems may interoperate only with other test systems, while production systems interoperate only with other production systems.
The DRMT contact for the Procedural Gateway is Jeff Lange.
Calling the TIP
In UWT1, AT programmers develop and test the PL/SQL application code that calls the TIP.
The general pattern for calling any TIP is to first make an INITIALIZATION
call, then make one or more useful TRANSACTION call, and finally to make
a TERMINATE call. An exception block should be coded to trap
errors and perform the TERMINATE call if that call has not already
been made normally.
-------------------------
PROCEDURE sample
IS
-------------------------
trannum BINARY_INTEGER:= 0;
/* transaction usage number
*/
rc
BINARY_INTEGER:= 0 ; /* return code
*/
terminated BOOLEAN:= FALSE;
/* FALSE until term function called */
instr ip0210.ip0210_IN_TYP;
/* transaction input string
*/
outstr ip0210.ip0210_OUT_TYP;
/* transaction output string
*/
BEGIN
-- While all this initializing seems quite a
pain,
-- I did encounter Oracle "numeric or value
errors"
-- if I did not do it.
instr.INPUT_PROGRAM_CONTROL:= '
';
instr.INPUT_SUB_MOD_DEMOGRAPH:=
' ';
instr.INPUT_SUB_MOD_CAMP_ADDR:=
' ';
instr.INPUT_SUB_MOD_EMAIL_ADDR:=
' ';
instr.INPUT_SUB_MOD_HOME_ADDR:=
' ';
instr.INPUT_SUB_TAX_INFO:= ' ';
instr.INPUT_SSN:= ' ';
instr.INPUT_OPERATOR_LOGON:= '
';
instr.INPUT_PERSON_ID := ' ';
instr.INPUT_GENDER:= ' ';
instr.INPUT_BIRTHDATE:= ' ';
instr.INPUT_HERITAGE_CODE:= '
';
instr.INPUT_PERSON_NAME:= ' ';
outstr.OUTPUT_MESSAGE_AREA:= '
';
outstr.OUTPUT_ERROR_RETURN:= '
';
outstr.OUTPUT_SQL_CODE:= ' ';
outstr.OUTPUT_PROGRAM_CONTROL:=
' ';
outstr.OUTPUT_PERSON_ID:= ' ';
outstr.OUTPUT_GENDER:= ' ';
outstr.OUTPUT_BIRTHDATE:= ' ';
outstr.OUTPUT_HERITAGE_CODE:=
' ';
outstr.OUTPUT_PERSON_NAME:= '
';
rc:= ip0210.ip0210_init(trannum); /* initialize transaction */
instr.input_program_control:= 'R';
-- R = Read
instr.input_ssn
:= '123456789';
rc := ip0210.ip0210_call(trannum,
instr,
outstr);
IF rc = 0 THEN
dbms_output.put_line('Hey,
it worked!');
dbms_output.put_line(‘person_name='
|| outstr.output_person_name);
END IF;
terminated:= TRUE;
/* says, "term function has been called" */
rc:= ip0210.ip0210_term(trannum,
0); /* terminate normally */
EXCEPTION
WHEN OTHERS
THEN
dbms_output.put_line('Into Exception Handler...');
IF NOT terminated THEN /* term not called yet; do so
now. */
rc:= ip0210.ip0210_term(trannum, 1); /* abnormal termination */
END IF;
RAISE;
END; /* procedure sample */
Move to Production
Error Messages and Codes
ORA-20910 with rc=22, errno=118
Possibility #1: The mainframe IMS transaction or its PSB is stopped.
Possibility #2: The started task (APPCBRDG) on the mainframe is not running correctly. DoIT SYSOPS has instructions for stopping and restarting the process.
Possibility #3: Has this IMS transaction never run successfully
thru the Procedural Gateway? Then DRMT has missed an authorization
step. The IMS transaction requires an ACF2 authorization on the mainframe.
Request Doit End User Computing to authorize the user IMSDFLT as a user
of the tran. DRMT is supposed to make this request when generating
a new test or production TIP.
ORA-12203: TNS:unable to connect to destination – trouble
with one or both Oracle listeners on Humvee/Ziggy. DoIT CSM and SYSOPS
have instructions for recycling the listeners.
ORA-04031 Unable to allocate <n> bytes of shared memory.
This is, as stated in the message, a shortage of memory, or a condition
where the Oracle server’s memory has become so fragmented over time that
loading a large PL/SQL package into memory has become impossible.
TIPs are large PL/SQL packages. The last time this message was seen,
UWP1 had to be stopped and restarted in order to resolve the problem.
last revised 5-12-99