This chapter discusses how to configure and operate Oracle Access Manager for CICS TS. The following topics are included:
Oracle Access Manager for CICS TS provides the interface between Oracle Precompiler programs (COBOL, C, or PL/I languages) executing Oracle SQL in a CICS TS transaction, and an Oracle database. Oracle Access Manager for CICS TS communicates with an OSDI local database server or it communicates with a remote Oracle database. The target service or remote database is defined in a TNSNAMES entry that is used as input when the thread table is created. Each instance of Oracle Access Manager for CICS TS communicates directly with one OSDI service or one remote database.
All OSDI clients connect to a service address space using the bind mechanism. Oracle Access Manager for CICS TS connects to a service address space at startup time using an OSDI special purpose bind that is specific to multi-connection environments. This provides efficiencies when subsequent connections are created to service any requests from Oracle transactions in the CICS TS region.
Connections for Oracle CICS TS transactions, whether to a local or remote database, are created and reused based on criteria defined in the thread table, and they are assigned to a CICS TS transaction the first time that it accesses Oracle.
When the CICS TS transaction request requires work to be done in the Oracle database, processing is switched to a CICS TS subtask which contains an IBM Language Environment (LE) environment prepared for executing the Oracle client code (LIBCLNTS). The Oracle client code communicates with a local Oracle server through cross-memory services or with a remote server through Oracle networking socket calls to satisfy the request. Starting with Oracle9i Release 2, this direct use of socket calls eliminates the requirement of a Net Service in earlier releases.
You can run applications built with these Oracle products for z/OS under Oracle Access Manager for CICS TS:
Pro*COBOL
Pro*C
Pro*PL/I
The following figure shows the relationship between an application program and Oracle Access Manager for CICS TS.
Figure 11-1 CICS TS Adapter for an Application Program
Application programs are mapped to a particular instance of Oracle Access Manager for CICS TS by way of an adapter name. The adapter name is part of the Oracle stub linked with the application program, and will correspond to the adapter name provided when Oracle Access Manager for CICS TS is started.
In the figure, ORA0 is the example adapter name. It is assigned on the CICS TS side when Oracle Access Manager for CICS TS is started. Refer to "Step 8: Start Oracle Access Manager for CICS TS Adapter" and the START command details for more information about the adapter name. An adapter name gets associated with an application program when it is linked with an ORACSTUB stub. Refer to "Step 6: Generate the ORACSTUB Stub for CICS TS" for details on generating an ORACSTUB stub.
Oracle Access Manager for CICS TS must be installed successfully before you can configure it. Refer to Oracle Database Installation Guide for IBM z/OS on System z for more information. For information about installing CICS TS, refer to IBM document CICS Transaction Server for z/OS Installation Guide.
Steps to configure the Oracle Database.
A thread represents a connection to the database. It is maintained by Oracle Access Manager for CICS TS. All active CICS TS transactions that communicate with an Oracle server database use a thread.
A table, defined and assembled as a load module, defines threads and their characteristics to Oracle Access Manager for CICS TS. When you create the thread definition table, configure the threads to match the expected workload and priorities for Oracle Access Manager for CICS TS users and applications.
Note:
The thread table must be reassembled if it was built on a version before release 9.2.Before defining your table, select a table name appropriate for your installation. The table name is specified to Oracle Access Manager for CICS TS at startup in the Oracle Access Manager for CICS TS START command.
Note:
You can also use the thread definition table to create automatic startup and shutdown (PLTPI and PLTSD) programs.Complete these steps to build the thread definition table.
Consider these criteria in determining the requirements for each transaction:
The authorization assignment specified in the AUTH parameter
The peak and average rates of the transaction
Whether the transaction requires dedicated threads
Whether Oracle COMMIT processing or CICS SYNCPOINT is to be used for commit and rollback functions. For more information, refer to "Recovery Considerations".
When you define a thread table:
Use the TRANSAC parameter to group transactions according to similar characteristics. If a transaction requires dedicated threads, then you should be sure to give it a separate definition.
Use the COPIES parameter to specify the number of threads you need to define for each group.
Base the thread definition on the peak and average rates of the transaction. The specified value must be large enough to handle a workload for the number of transactions specified in the TRANSAC parameter.
Use the PROTECT parameter to specify how to protect the threads defined in the COPIES parameter. The session is not dropped, even if the IDLE TIME has expired.
Use the WAIT parameter to specify the action to take if no thread is available.
The following table contains descriptions of the thread definition table parameters:
Table 11-1 Thread Definition Table Parameters
Parameter | Description |
---|---|
|
is used, if specified, as the Oracle user ID for the control thread. It must be a constant character string of 30 characters or less, and requires the AM4CAUTH parameter. If omitted, then the CICS APPLID is used for autologon. This parameter is specified on the TYPE=START statement. |
|
is the authentication string (password) for the Oracle user ID specified in the AM4COID parameter. It must be a constant character string of 30 characters or less. This parameter is specified on the TYPE=START statement. |
|
determines how the Oracle user ID is derived without an explicit connect statement. The Oracle user ID is also used for SMF accounting. |
CINTERVL |
specifies the control transaction time interval. This interval is used to determine how frequently unprotected idle threads are dropped. Idle threads defined with PROTECT=YES are not affected by the setting of CINTERVL. The interval also affects the length of time it can take Oracle Access Manager for CICS TS to invoke emergency shutdown when the Oracle server cannot be contacted. The value is expressed in minutes and seconds, and valid values range from 0000 to 5959. The default value is 0030 (00 minutes, 30 seconds). |
|
specifies whether to use Oracle COMMIT processing or CICS SYNCPOINT for commit and rollback functions. Valid values are CICS and ORACLE. The default is ORACLE. This parameter can also be specified on the TYPE set to START statement or the Oracle Access Manager for CICS START command. Refer to "Recovery Considerations" for information about these parameter values. |
|
indicates the number of threads this definition generates. |
|
defines the z/OS descriptor code used for the console message. Valid values are numeric. The default is 11. DESC is an optional parameter. |
ENAME |
is used in conjunction with TYPE=ENV to specify environment variables for Oracle Access Manager for CICS TS. It is useful for setting the NLS environment variables to values appropriate for your environment. The syntax is: ENAME=(var=val, ...) where The following example shows a single ENAME parameter being used to specify NLS_LANG and NLS_DATE_FORMAT: ORACICS TYPE=START,SSN=ORA0 ORACICS TYPE=THREAD,COPIES=30,PROTECT=NO, X TRANSAC=* ORACICS TYPE=ENV, X ENAME=(NLS_LANG=AMERICAN_AMERICA.WE8EBCDIC37C, X NLS_DATE_FORMAT=DD-MON-RR) |
|
defines the amount of free space to be allocated for later additions. This parameter is not implemented. |
|
defines the maximum number of cursors used. The MAXCRSR parameter is patterned after the precompiler option MAXOPENCURSORS. Refer to the Pro*C/C++ Precompiler Programmer's Guide for more information about the MAXOPENCURSORS option. The default is 10. |
|
defines the maximum number of threads allocated for this table definition. If the total threads for the table exceed this value, then the MAXTHRD value is adjusted. The default is 10. |
|
identifies the adapter you want started. If NAME is not specified, then the started adapter name defaults to the thread table name. This parameter only applies if TYPE is set to PLTPI. |
|
is used, if specified, as the Oracle user ID for this thread definition, including all threads generated with the COPIES parameter. It must be a constant character string of 30 characters or less. When specified, the value in the AUTH parameter is used as the associated authentication string. |
|
specifies whether Oracle Access Manager for CICS TS subtasks are run at a higher or lower priority than the current dispatching priority when subtasking is used. Valid values are HIGH and LOW. If HIGH is specified, then Oracle Access Manager for CICS TS subtasks are run at a higher dispatching priority. If LOW is specified, then Oracle Access Manager for CICS TS subtasks run at a lower dispatching priority. LOW is the default. |
|
specifies the name of the program used with the Oracle Access Manager for CICS TS transaction. ORACICS is the default. This parameter only applies if TYPE is set to PLTSD. |
|
specifies whether a thread is protected. Valid values are YES, NO, and |
|
defines the z/OS route code to use when writing messages to the z/OS operator console. The default is 11. |
|
specifies the alias name used for the Oracle Net connection (as specified in the TNSNAMES entry used as input to the CIN step of the TBLJCLN job in SRCLIB) for database access. The alias must be four characters or fewer. |
|
specifies the name of the program for CICS PLTPI processing when TYPE is set to PLTPI. |
|
specifies the name of the adapter stopped during PLTSD shutdown processing. This name corresponds to the value of the NAME parameter used if shutdown processing is performed manually with the STOP command. |
|
specifies the transaction codes eligible to use the thread. A value of * indicates the thread is to be used as a default and no other definitions apply. |
|
specifies the action to be taken when all threads specified for a transaction are in use. Valid values are YES, NO, and POOL. YES indicates the transaction is placed in a CICS WAIT state until a thread is available. NO indicates a return code is set indicating no threads are available. POOL indicates the general thread pool (TRANSAC=*) is used. YES is the default. |
Two additional thread definition table parameters (AUTH and TYPE) are described in the following sections.
A maximum of three values can be specified for AUTH. Valid values are listed in the following table:
Table 11-2 Valid Values for AUTH
Value | Description |
---|---|
OPID |
based on the operator id. |
PROGRAM |
causes the Oracle user ID to be derived from the program name. |
PROXY |
causes the Oracle user ID to be derived from the CICS signon (CESN) user ID, with the control thread as an authentication proxy. When this option is specified, the control thread must include the AM4COID and AM4CAUTH options. |
|
causes the Oracle user ID to be derived from the terminal identification. |
|
causes the Oracle user ID to be derived from the transaction id. |
|
causes the Oracle user ID to be derived from the CICS user ID. |
authorization string |
causes the Oracle user ID to be the specified constant character string if the OID parameter is not specified. The implied Oracle user ID is derived by prefixing OS_AUTHENT_PREFIX, for example, the string OPS$ to the value specified by this AUTH parameter. If the OID parameter is specified, then this is the authentication string (password) used for that Oracle user ID. OS_AUTHENT_PREFIX will not be prefixed to this string. For example, by specifying AUTH='SCOTT', OPS$SCOTT is used as the Oracle user ID. |
TYPE is a parameter specifying the type of entry being defined. Valid values are listed in the following table:
Table 11-3 Valid Values for TYPE
Value | Description |
---|---|
|
indicates the previous definition is being continued. |
ENV |
is used in conjunction with the ENAME parameter to specify environment variables for Oracle Access Manager for CICS TS. |
|
indicates the end of a table. |
|
indicates the beginning of the table and sets default values. |
|
indicates a thread is being defined. |
|
indicates PLTPI generation. For PLTPI generation, the only valid value is PLTPI. A value of PLTPI indicates this definition generates the PLTPI program for Oracle Access Manager for CICS TS. Refer to "Step 9.2: Using the PLTPI Program" for an example of a PLTPI generation statement. You must perform PLTPI generation separately from the thread table and PLTSD generation. |
|
indicates PLTSD generation. For PLTSD generation, the only valid value is PLTSD. A value of PLTSD indicates this definition generates the PLTSD program for Oracle Access Manager for CICS TS. Refer to "Step 9.3: Generate the PLTSD Program" for an example of a PLTSD generation statement. You must perform PLTSD generation separately from the thread table and PLTPI generation. |
This sample thread definition table resides in the SRCLIB library in the ORACICSD member:
ORACICS TYPE=START, X SSN=ORA0, X MAXTHRD=30, X MAXCRSR=5 ORACICS TYPE=THREAD, X COPIES=4, X PROTECT=2, X TRANSAC=(TTRN,TRN2,TRN3) ORACICS TYPE=CONTINUE, X TRANSAC=(TRN9,TRNA) ORACICS TYPE=THREAD, X COPIES=4, X PROTECT=NO, X TRANSAC=(TRN1,TRNT,TRN4), X AUTH=(USERID,'STRING') ORACICS TYPE=THREAD, X COPIES=4, X PROTECT=NO, X TRANSAC=(TRN5,TRN6,TRN7), X AUTH='AUTHORIZATION_STRING' ORACICS TYPE=THREAD, X COPIES=4, X PROTECT=NO, X TRANSAC=TRN8 ORACICS TYPE=THREAD, X COPIES=4, X PROTECT=NO, X TRANSAC=* ORACICS TYPE=END END
You can specify authorization in the thread table, as follows:
To use an explicit Oracle id for the control thread, use the AM4COID and AM4CAUTH parameters on the TYPE=START. For example, to use control thread user ID AM4CICS and authorization ORACLE, include the following parameters:
ORACICS TYPE=START,AM4COID='AM4CICS',AM4CAUTH='ORACLE'
To define threads to use an explicit Oracle id, use the OID and AUTH parameters on the TYPE=THREAD entry. For example, to use user ID SCOTT and authentication TIGER for transactions TTRN, TRN2, and TRN3 in the above example, include the following parameters in the TYPE=THREAD statement:
OID='SCOTT',AUTH='TIGER'
Use the parameter AUTH='authorization_string'
to define threads using a constant character string. The parameter AUTH='authorization_string'
derives the Oracle user ID and provides the highest level of thread sharing and throughput. AUTH set to TRANSID or AUTH set to PROGRAM performs equally only if one TRANSID or PROGRAM uses a thread definition. This type of authentication is only valid against a local database. For example:
OS_AUTHENT_PREFIX=OPS$
is defined as an init.ora
file parameter
User ID OPS$SCOTT
has been created as CREATE USER OPS$SCOTT
identified externally
To use for transactions TRN9 and TRNA, add the AUTH='SCOTT'
parameter in the TYPE=THREAD statement in the previous example.
The values in the AUTH parameter are used in the order specified. AM4CICS attempts to reuse a free connected thread. If there are no free threads with an active authorization matching the current request (the same @Oracle user ID), a logon will be performed using the first valid authorization option. Only if the first option is invalid (for example, AUTH=USERID but the user did not signon to CICS), will the second or third authorization options be used.
An explicit connect statement takes priority regardless of the authentication specified on the TYPE=THREAD statement. However, the thread and database connection is reset at transaction-end with this method and therefore additional overhead is incurred.
These conditions apply to thread table definitions:
If a transaction code does not have an associated thread table definition, then the general thread pool definitions (TRANSAC=*) are used.
If all threads for a transaction are in use and the WAIT parameter specifies POOL, then the thread used has all the characteristics defined in the TRANSAC=* definition. The transaction thread characteristic is not carried over to the pool thread.
The sample JCL in SRCLIB library member TBLJCLN assembles and links the threadtable.
Oracle Net allows multiple entries in the TNSNAMES data set. Oracle Access Manager for CICS TS must have its entry as the only entry.
In the INFILE DD statement in the first step (CIN), specify your TNSNAMES data set containing your TNS connect descriptor and alias for CICS. The alias name for CICS must be four characters or fewer and must match the SSN parameter specified in the thread table definition or the SSN override parameter on the START command. There must be only one entry used by CICS. You might need to create a separate PDS member from one of the TNSNAMES entries for the CICS. The service name or alias must be on a separate line from the rest of the connect descriptor. A TNSNAMES specification for Oracle Access Manager might be similar to the following:
ORA0=
(DESCRIPTION= (ADDRESS= (PROTOCOL=TCP) (HOST=HQUNIX) (PORT=1533)) (CONNECT_DATA=(SID=ORA0)))
For a local database, the TNSNAMES specification might be similar to the following:
ORA0=
(DESCRIPTION= (ADDRESS= (PROTOCOL=xm) (SID=ORA0)))
In the SYSLMOD DD statement, specify the name of the data set where the table load module resides. The load module name is the table name used in the MOD parameter or the START command.
If you want to install a revised thread table while CICS TS is executing, then perform these steps:
Ensure that you have reassembled the table as described in "Step 1.3: Assemble and Link Thread Table".
Issue the STOP command for the adapter.
Define the thread definition table to CICS TS using the CEDA command:
CEDA DEFINE PROGRAM(tablename) LANG(ASSEMBLER) GROUP(groupname)
where:
Table 11-4 Variable Description for Code Example
Variable | Description |
---|---|
|
is the name of your thread definition table. |
|
is the name of the group, typically ORACLE. |
Issue the CICS TS master terminal command to install the revised thread table where tablename is the name of the revised thread definition table:
CEMT SET PRO(tablename) NEW
Issue the START command for the adapter.
You can make the MESG Library available to CICS TS in one of two ways:
Add an ORA$LIB DD statement to the CICS JCL specifying the MESG library data set name.
Concatenate the MESG library data set name to the CICS STEPLIB DD concatenation.
Note:
This library must be authorized to be in CICS STEPLIB.Copy the ORACICSC and LIBCLNTS modules from the Oracle CMDLOAD library to an authorized library in the CICS STEPLIB concatenation. This library must be a PDSE library.
Copy the ORACICS and CICADPX modules from the Oracle CMDLOAD library to a library in the CICS DFHRPL concatenation or alternatively, add the Oracle CMDLOAD library to the CICS DFHRPL concatenation.
If you are accessing a remote server, ensure that the CICS address space is dubbed, as described in the section "Client Authorizations".
Oracle Access Manager for CICS TS establishes a database connection at startup
to manage idle connections,
and to verify that Oracle services are available during execution.
You must define Oracle Access Manager for CICS TS as an Oracle user by one of the following methods:
If you are using AM4COID and AM4CAUTH in the thread table, then the user ID is the value specified in the AM4COID parameter. For example, if AM4COID=AM4CICS and AM4CAUTH=AMTHREAD, then the following statements would be used to define Oracle Access Manager for CICS TS:
CREATE USER AM4CICS IDENTIFIED BY AMTHREAD; GRANT CREATE SESSION TO AM4CICS;
If you are not using AM4COID and AM4CAUTH, then the Oracle Access Manager control thread uses OS authenticated logon based on the CICS APPLID (for a local database) or CICS job name (for a remote database). Refer to Oracle Database Administrator's Guide for more information about OS authenticated logins. The OS_AUTHENT_PREFIX initora parameter is prefixed to the CICS APPLID to create the Oracle user ID. For example, if OS_AUTHENT_PREFIX = "" (null prefix), and if the CICS applid is CICSAPPL, then the following statements would be used to define Oracle Access Manager for CICS TS:
CREATE USER CICSAPPL IDENTIFIED EXTERNALLY; GRANT CREATE SESSION TO CICSAPPL;
Note:
If a local database is accessed and the CICS applid is used, it is important to review the LOGON_AUTH setting in the Database Service definition.To enable FORCE and SELECT privileges for recovery processing if COMMIT is set to CICS (that is, if CICS SYNCPOINT processing is used instead of Oracle COMMIT), then you must issue the following SQL statements, where userid
is the Oracle Access Manager for CICS TS user ID from above:
GRANT FORCE ANY TRANSACTION TO userid; GRANT SELECT ON SYS.PENDING_TRANS$ TO userid; GRANT SELECT ON SYS.PENDING_SESSIONS$ TO userid;
If any application programs uses proxy authorization (AUTH=PROXY), then you must issue the following SQL statement, where cics_user is CICS signon (CESN) user ID and AM4COID is the Oracle user ID specified for the control thread:
ALTER USER cics_user GRANT CONNECT THROUGH AM4COID;
Note:
Data dictionary view PROXY_USERS may be used to check which users have the control thread as a proxy.You must complete the following steps on the server for Oracle Access Manager for CICS TS. For additional information, refer to the Oracle server installation documentation.
If the database server is a localbOSDI database service, then review the Database Region Parameter, IDLE_TIMEOUT. Do not use this parameter if PROTECT=YES is used or the TYPE=THREAD statement is in the thread table. If PROTECT=NO, ensure this setting is at least twice the value of CINTERVL in the TYPE=START statement.
If you are preparing a remote host for Oracle Access Manager for CICS TS, and if OS authenticated logon is being used in step 4, then set the INITORA parameter REMOTE_OS_AUTHENT to TRUE on the remote database.
If OS authenticated logon is being used, then ensure that the value of the INITORA parameter OS_AUTHENT_PREFIX on the remote database is used in the GRANT statements in "Step 4: Define CICS TS to Oracle and Grant Privileges".
To generate the ORACSTUB stub for CICS TS:
Determine your CICS TS adapter name.
Create the generation statement. Refer to SRCLIB library member ORACSTB for an example.
Generate ORACSTUB. Refer to SRCLIB library member ORACSJCL for an example.
Relink your Oracle Precompiler programs with the generated ORACSTUB. Place the library containing ORACSTUB in the SYSLIB concatenation of the link JCL and insure the SYSLIN DD contains an INCLUDE SYSLIB (ORACSTUB) statement.
If you are running CICS TS release 2.2 or less, then complete Steps 7.1 through 7.3.
If you are running CICS TS release 3.0 or higher, then do not perform Step 7. Instead, use the RDO definition statements in member ORACSD of the Oracle SRCLIB library as SYSIN for JCL to invoke DFHCSDUP. Before you submit the job, remove all comments. Change the appropriate data set names in the DD statements as appropriate for your site.
After successful completion, issue this RDO command to install the CICS tables:
CEDA INSTALL GROUP (ORACLE)
Proceed to "Step 8: Start Oracle Access Manager for CICS TS Adapter".
Before you can use Oracle Access Manager for CICS TS, you must define several resources to CICS by specifying CICS CEDA transactions.
Normally definitions for resources used by CICS, such as programs and transactions, are contained in GROUPS containing logically related resources. A GROUP is created when it is first specified in a CEDA DEFINE command. In these examples, the assigned GROUP name is ORACLE.
Issue these commands to define the programs used by Oracle Access Manager for CICS TS to CICS:
CEDA DEFINE PROGRAM(ORACICS) GROUP(ORACLE) LANGUAGE(ASSEMBLER) CEDA DEFINE PROGRAM(CICADPX) GROUP(ORACLE) LANGUAGE(ASSEMBLER)
After executing each CEDA DEFINE command, CICS displays the message DEFINE SUCCESSFUL at the bottom of a full screen panel.
To end a current CEDA transaction before entering a new command, press the [PF3] and [Clear] keys.
Once you have specified the programs, define the Oracle Access Manager for CICS TS control transaction with this command. Enter the command string on one line:
CEDA DEFINE TRANSACTION(xxx) GROUP(ORACLE) TWASIZE(0) PROGRAM(ORACICS)
where xxx
is the name of the transaction you use as the Oracle Access Manager for CICS control transaction.
Note:
The Oracle Access Manager control transaction also requires you to specify the TASKDATAKEY(CICS) parameter.To make Oracle Access Manager for CICS TS available to CICS TS transactions, you must start the Oracle Access Manager for CICS TS adapter. An adapter is a CICS TS program that interfaces between transactions and a system such as Oracle. To start the adapter, you can use:
transaction START MOD(module)
where:
Table 11-5 Variable Descriptions for Code Example
Variable | Description |
---|---|
|
is the name of the assembled thread definition table containing the Oracle Access Manager for CICS TS control transaction. |
|
is the Oracle Access Manager for CICS TS control transaction. |
For example, if the control transaction is ORA2 and the assembled thread definition table name is ORA0, you issue the command:
ORA2 START MOD(ORA0)
If the START command is successfully executed, the connection between CICS TS and Oracle is successfully established.
If you want to initialize Oracle Access Manager for CICS TS automatically at CICS initialization time and automatically shutdown Oracle Access Manager for CICS TS at CICS TS termination, then the Oracle Access Manager for CICS TS control program must be invoked during CICS TS startup and shutdown. This step is optional. You can run ORACICS at CICS TS initialization by using a CICS TS provided initialization parameter or by using the PLTPI facility. At CICS TS termination, you can run ORACICS by using of the PLTSD facility.
The CICS TS System Initialization Parameter (SIT) INITPARM can be used to run ORACICS. This can be in the SIT table or specified as a startup override. The advantage of this method is that Access Manager for CICS is fully initialized before the "Control is being given to CICS" point.
For example:
INITPARM=(ORACICS='ORAC START MOD(ORA0)')
where ORAC is the Access Manager for CICS transaction code and ORA0 is the thread table name.
You can use any valid startup command.
The ORACICS macro generates a command level CICS TS program that is added to the CICS PLTPI table for automatic initialization during CICS TS startup. An example of the command to generate the PLTPI program is:
ORACICS TYPE=PLTPI,START=ORA0,TRANSAC=ORA2
In this example, ORA0 is the thread table definition and ORA2 is the Oracle Access Manager for CICS TS control transaction. This command is equivalent to issuing one of these commands from a terminal:
ORA2 START MOD(ORA0)
or
ORA2 START ORA0
The ORACICS TYPE=PLTPI statement is used as input to the assembly procedure and produces an assembler language CICS TS command-level program.
Use the following JCL to create the PLTPI program:
//ORAPLTPI JOB (ORA),'Oracle PLTPI PROGRAM' //CIN EXEC PGM=CINAMES,REGION=4000K //* //STEPLIB DD DSN=ORACLE.V10G.CMDLOAD,DISP=SHR //SYSIN DD DUMMY //SYSOUT DD SYSOUT=* //SYSERR DD SYSOUT=* //* REPLACE INFILE WITH USER TNSNAMES SOURCE TO BE USED FOR CICS //INFILE DD DISP=SHR,DSN=ORACLE.ORA1.PARMLIB(TNSNAMES) //OUTFILE DD DSN=&&TEMPPDS(CINAMES), // UNIT=SYSDA,DISP=(,PASS), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=400), // SPACE=(400,(100,100,5)) //ASM EXEC PGM=IEV90,REGION=4000K //SYSPRINT DD SYSOUT=* //SYSLIB DD DSN=&&TEMPPDS,DISP=(OLD,DELETE) // DD DSN=ORACLE.V10G.MACLIB,DISP=SHR // DD DSN=CICS.MACLIB,DISP=SHR // DD DSN=SYS1.MACLIB,DISP=SHR //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(5,5)) //SYSPUNCH DD ***dataset for assembler pltpi source program //SYSIN DD * ORACICS TYPE=PLTPI,START=ORA0,TRANSAC=ORA2 /*
The ORACICS macro generates a command-level program that is added to the CICS PLTSD table for automatic shutdown during CICS termination. An example of the command to generate the PLTSD program is:
ORACICS TYPE=PLTSD,PROGRAM=ORACICS,STOP=ORA0
In this example, ORACICS
is the name of the Oracle Access Manager for CICS TS control program and ORA0 is the name of the CICS TS adapter to be stopped. This command is equivalent to issuing the terminal command:
ORA2 STOP NAME(ORA0)
The ORACICS TYPE=PLTSD statement is used as input to the assembly procedure and produces an assembler language CICS TS command-level program.
Use the following JCL to create the PLTSD program:
//ORAPLTSD JOB (ORA),'Oracle PLTSD PROGRAM' //CIN EXEC PGM=CINAMES,REGION=4000K //* //STEPLIB DD DSN=ORACLE.V10G.CMDLOAD,DISP=SHR //SYSIN DD DUMMY //SYSOUT DD SYSOUT=* //SYSERR DD SYSOUT=* //* REPLACE INFILE WITH USER TNSNAMES SOURCE TO BE USED FOR CICS //INFILE DD DISP=SHR,DSN=ORACLE.ORA1.PARMLIB(TNSNAMES) //OUTFILE DD DSN=&&TEMPPDS(CINAMES), // UNIT=SYSDA,DISP=(,PASS), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=400), // SPACE=(400,(100,100,5)) //ASM EXEC PGM=IEV90,REGION=4000K //SYSPRINT DD SYSOUT=* //SYSLIB DD DSN=&&TEMPPDS,DISP=(OLD,DELETE) // DD DSN=ORACLE.V10G.MACLIB,DISP=SHR // DD DSN=CICS.MACLIB,DISP=SHR // DD DSN=SYS1.MACLIB,DISP=SHR //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(5,5)) //SYSPUNCH DD ***dataset for assembler pltsd source program //SYSIN DD * ORACICS TYPE=PLTSD,PROGRAM=ORACICS,STOP=ORA0 /*
Use the generated assembler language CICS TS command-level programs (PLTSD and PLTPI) as input to the CICS DFHEITAL procedure.
Add the user-defined name of the load module containing the generated program for PLTPI (output of the DFHEITAL procedure) to the PLTPI table. If your output from DFHEITAL is named ORAPLTI, then you can also name your load module ORAPLTI. For example:
CEDA DEFINE PROGRAM(ORAPLTI) GROUP(ORACLE) LANGUAGE(ASSEMBLER)
Define the load module to CICS TS with a CEDA DEFINE command. The generated program can be modified to include override parameters.
This program must be placed after PROGRAM=DFHDELIM in the CICS PLTPI table.
Add the user-defined name of the load module containing the generated program for PLTSD (output of the DFHEITAL procedure) to the CICS PLTSD table. If your output from DFHEITAL is named ORAPLTS, then you can name your load module ORAPLTS. For example:
CEDA DEFINE PROGRAM(ORAPLTS) GROUP(ORACLE) LANGUAGE(ASSEMBLER)
Define the load module as a program to CICS TS with a CEDA DEFINE command.
The following steps are optional.
The Oracle SRCLIB library contains these procedures for preparing high-level language programs. Modify these procedure names according to your site's naming conventions and move them to an appropriate procedure library if necessary.
SRCLIB member OSAMPLE is a COBOL II program that displays an employee name from the EMP table. To use the sample program, you must:
Ensure the EMP table is on the database.
Ensure SCOTT/TIGER is a valid logon id on the database. Also ensure SCOTT /TIGER has access to the EMP table.
Ensure "Step 6: Generate the ORACSTUB Stub for CICS TS", is completed.
Tailor the JCL in SRCLIB member CICSPCC2 for your installation. Then execute CICSPCC2 to compile OSAMPLE. This places OSAMPLE into a library in the CICS DFHRPL concatenation.
Define the program OSAMPLE to CICS TS by using standard RDO procedures.
Define a transaction to CICS TS (for example, OSAM) using standard RDO procedures and associate it with the OSAMPLE program.
Once the START command is issued for Oracle Access Manager for CICS TS, you can invoke the transaction.
This version of Oracle Access Manager for CICS TS can coexist in the same CICS TS region with a version before release 9.2. For example, release 10.1 can coexist with release 9.0.x or earlier, but not with a release 9.2.x.
To configure a second version, perform the following steps:
(This step is required only if both versions will be executing concurrently. If not, go to Step 2.) If both versions will be executing concurrently, create an ORACSTUB stub specifying the adapter name that has been chosen for the 10.1 version. This will be linked with applications programs accessing the 10.1 version.
This version uses the ORACICS load module. If a prior version uses the ORACICN load module name as distributed, there is no conflict.
Define a second control transaction to CICS TS, associating this transaction with the ORACICS program.
Resource recovery is determined by whether COMMIT (CICS) or COMMIT (Oracle) was designated to Oracle Access Manager for CICS TS as the recovery choice in the thread definition table parameter COMMIT.
CICS TS maintains and recovers its own protected resources (that is, VSAM data sets, DL/I databases, and so forth) with the use of the SYNCPOINT and ROLLBACK commands. Use SYNCPOINT to indicate a logical unit of work is complete and does not need to be backed out in case of failure. Use ROLLBACK to indicate a logical unit of work is incomplete and changes must be backed out in case of failure.
When a CICS TS transaction syncpoints explicitly by issuing an EXEC CICS SYNCPOINT or implicitly at transaction end, Oracle Access Manager for CICS TS ensures all Oracle server updates in the logical unit of work (LUW) are committed or backed out. Use the Oracle two-phase commit support to accomplish this.
A transaction abend, ORAP, error occurs if you specify the CICS option and an Oracle EXEC SQL COMMIT or EXEC SQL ROLLBACK is issued.
When using CICS syncpoint for commit and rollback functions(COMMIT=CICS), the Oracle Access Manager for CICS adapter uses the SSN parameter to form the transaction identifier for recovery. If there are multiple adapters in the same CICS region which access the same Oracle database, the SSN parameter must be unique for each adapter. The SSN parameter can be specified in the thread table or, if the same thread definition table is used for each adapter, the SSN parameter can be changed with the SSN startup parameter.
Oracle has its own recovery mechanism, independent of CICS TS, and uses the COMMIT and ROLLBACK SQL commands to control it. To commit or rollback Oracle changes, an application must issue an EXEC SQL COMMIT or EXEC SQL ROLLBACK. If an application does not issue a COMMIT or ROLLBACK SQL command, then all outstanding Oracle database updates are rolled back at the end of the CICS TS transaction.
A CICS SYNCPOINT also does not perform a SQL COMMIT, nor does a SQL COMMIT perform a CICS SYNCPOINT. If an application is performing update operations on both CICS protected resources and Oracle tables, then the application must issue both a CICS SYNCPOINT and a SQL COMMIT to affect both sets of resources.
When CICS syncpoint processing is selected as the resource commit or recovery choice, Oracle Access Manager for CICS TS can participate in two-phase commit processing under CICS TS.
CICS TS serves as the coordinator and Oracle Access Manager for CICS TS uses the two-phase commit protocol to interface with the Oracle server.
This process is transparent to the transaction. Oracle Access Manager for CICS TS implements the CICS syncpoint resource manager interface, enabling Oracle resources to participate in CICS distributed transactions and removing the requirement that Oracle COMMIT and ROLLBACK commands be issued in addition to the CICS SYNCPOINT command.
To use the CICS syncpoint resource manager interface, you must specify CICS as the recovery choice in the thread table or as a startup option. You can specify the option by:
Using the COMMIT thread table parameter
For more information, refer to the "Thread Definition Table Parameters".
Using the COMMIT parameter on the START command
For more information, refer to the START command description.
In the first phase of the two-phase commit protocol, the CICS syncpoint manager presents a PREPARE request, which requests a promise to commit or rollback the transaction to Oracle Access Manager for CICS TS. Oracle Access Manager for CICS TS communicates with the Oracle servers and returns one of three responses to the CICS syncpoint manager:
Table 11-7 Responses to CICS Syncpoint Manager
Response | Description |
---|---|
|
indicates the Oracle server could not complete the CICS PREPARE request. |
|
indicates the Oracle server has all resources necessary to subsequently commit and rollback the transaction. When the prepare phase is completed, the transaction is said to be in-doubt. |
|
indicates no data has been modified so no |
The second phase of two-phase commit processing is the commit phase. The CICS syncpoint manager presents a COMMIT/ROLLBACK request to Oracle Access Manager for CICS TS. Oracle Access Manager for CICS TS then communicates with the Oracle server to complete the processing.
Failures can result during two-phase commit processing. These items are in-doubt resolutions:
CICS TS warm or emergency restart
Oracle server restart
Manual recovery
In this case, CICS TS has access to a log of in-doubt LUWs. When Oracle Access Manager for CICS TS starts, it resynchronizes with CICS TS and the Oracle server to obtain the transactions that are in-doubt, and communicates with the Oracle server to complete two-phase commit processing.
LUWs that include Oracle and other CICS TS recoverable resources can be lost if CICS TS is started cold and the LUWs might require manual resolution.
When Oracle Access Manager for CICS TS detects an Oracle server restart, it resynchronizes in-doubt Oracle server LUWs with CICS TS and communicates with the Oracle server to complete two-phase commit processing.
Oracle in-doubt CICS TS transactions should not be manually committed or rolled back using the FORCE command. However, some situations, such as a CICS TS cold start, might require manual intervention. The Oracle server maintains a pending transaction view, DBA_2PC_PENDING. The GLOBAL_TRAN_ID in DBA_2PC_PENDING for CICS TS transactions is the concatenation of these fields in the order shown:
Table 11-8 Concatenated Fields for GLOBAL_TRAN_ID
Field Name | Description |
---|---|
OPS |
is the eight character CICS applid, or the value of AM4COID in the thread table. |
|
is the four-character name of an Oracle Access Manager for CICS TS adapter. |
|
is eight characters and represents the value of the logical unit of work obtained from CICS TS. |
For more information about the OPS$applid
and adapter
name
fields, refer to "Configuration Steps" in this chapter. For additional information about using DBA_2PC_PENDING for manual recovery, refer to Oracle Database Administrator's Guide.
To shut down Oracle Access Manager for CICS TS forcibly, use the STOP command with the IMMEDIATE FORCE parameter. When the IMMEDIATE FORCE parameter is used with the STOP command, Oracle Access Manager for CICS TS terminates all threads and shuts down. Caution must be used with this parameter. The shutdown is not an orderly shutdown. For more information, refer to the STOP command.
If you start Oracle Access Manager for CICS TS after you start the Oracle server, then automatic restart takes effect when Oracle terminates. When the Oracle server is restarted, Oracle Access Manager for CICS TS automatically restarts and resynchronizes any in-doubt logical units of work. If you start Oracle Access Manager for CICS TS before the Oracle server, then you must perform the initial start of Oracle Access Manager for CICS TS manually.
You can use CICS EDF to debug Oracle Access Manager by transaction. SQL statements are shown on the EDF screen before and after each transaction is run. To begin an EDF session, start the adapter and include the keyword EDF. For example:
ORA2 START MOD(ORA0) EDF
A connect statement will only display as "connect." There is no user ID and password information displayed.
SQL statements are displayed as coded; the values for variables are not resolved.
Oracle Access Manager for CICS TS uses the PL/SQL package dbms_application_info
to maintain the following fields in the V$SESSION table. Session information is updated for each CICS TS transaction when the database is first accessed:
The Module field contains the initial application program name.
The Client_info field contains 16 bytes of information, as follows:
CICS transaction code(4) column 1-4 CICS terminal id(4) column 5-8 CICS userid(8) column 9-16
The following are three scenarios for determining whether Oracle Access Manager for CICS TS will restart automatically or must be restarted manually if the database becomes unavailable:
If Oracle Access Manager for CICS TS is in the process of starting up or shutting down and the database becomes unavailable, Oracle Access Manager for CICS TS must be restarted manually.
If Oracle Access Manager for CICS TS is running and it detects that the database is no longer available, it performs an emergency shutdown and issues message CIC-00026.
Transactions that are executing receive an ORAP abend or a CICS ASP7 abend, depending on their execution point. New transactions receive an ORAP abend or a CICS AEY9 abend or AETA abend.
Oracle Access Manager for CICS TS will monitor the database and when it becomes available, will automatically restart and issue message CIC-00007.
If Oracle Access Manager for CICS TS is accessing a local database and the database service is either stopped, canceled, or otherwise becomes unavailable due to an uncontrolled shutdown, then Oracle Access Manager for CICS TS will restart automatically under the control of a retry limit and a time interval.
The retry limit is the maximum number of times a loss of service condition will trigger automatic restart. To deactivate the mechanism, change the retry limit to 0. The default is 2 (for example, after 2 loss of OSDI service conditions have occurred, manual restart is required). If the limit is reached and another loss of service occurs, a CIC-99999 message stating that manual restart is required will immediately precede the CIC-00026 emergency shutdown message.
The time interval, in the form of hhmmss
, is the time to wait before first restart attempt when an OSDI loss of service occurs. Note that this time interval only applies in this situation. If the service is not available after this time interval, Oracle Access Manager for CICS TS continues to attempt a restart, but the time interval reverts to the normal, CINTERVAL value from the thread table. The default is 30 seconds.
A new display, similar to other Oracle Access Manager for CICS TS transaction displays, is provided to update the retry and interval fields. For example, if you enter ORA2 ALTER NAME (ORA0)
, where ORA2
is the control transaction, and ORA0
is the adapter name, you receive an ORA0 Alter display screen formatted with the current retry and interval values.
The values can be modified by typing over them. Pressing the ENTER key updates and redisplays the values so they can be verified.
Note:
The values can only be changed when the adapter is active. Therefore they cannot be modified when the restart mechanism is in progress.Pressing thePF3 key exits the Alter display. The values are reset to the defaults after a normal shutdown or startup of Oracle Access Manager for CICS TS.
Oracle Access Manager for CICS TS commands are entered with the transaction ID followed by the Oracle Access Manager for CICS TS command. The general format is:
trans_id command parms
where:
Table 11-9 Variable Description for Code Example
Variable | Description |
---|---|
|
is the Oracle Access Manager for CICS TS transaction ID (usually |
|
is the Oracle Access Manager for CICS TS command. |
|
is one or more parameters for the command. |
Oracle Access Manager for CICS TS commands can be entered in two ways:
You can enter the CICS transaction id (usually ORA2
) followed by the command. For example:
ORA2 DISPLAY NAME(ORA0)
In this case, the control transaction sends the display to the terminal.
You can enter only the transaction id for the control transaction. In this case, the control transaction prompts you for a command.
Use the [PF3] key to exit from the control transaction.
The following section contains information about DISPLAY.
DISPLAY NAME(adapter) DISPLAY TRAN() NAME(adapter) DISPLAY STATUS NAME(adapter)
where adapter
is the name of an Oracle Access Manager for CICS TS adapter.
This command enables to monitor your Oracle Access Manager for CICS TS system. The screen displayed varies according to which DISPLAY command is issued.
DISPLAY NAME displays a screen showing general information about an Oracle Access Manager for CICS TS system.
When the command:
ORA2 DISPLAY NAME(ORA0)
is issued, where ORA2
is the name of the transaction defined to control Oracle Access Manager for CICS TS and ORA0
is the name of the Oracle Access Manager for CICS TS adapter, the screen is displayed:
DISPLAY TRAN NAME displays a screen showing all the transactions defined in a thread definition table.
When the command:
ORA2 DISPLAY TRAN() NAME(ORA0)
is issued, where ORA2 is the name of the transaction defined to control Oracle Access Manager for CICS TS, TRAN()is the transaction identifier and ORA0 is the name of the Oracle Access Manager for CICS TS adapter, the screen is displayed.
You can specify the TRAN() parameter as follows:
TRAN - default all transactions TRNA(ZZZZ) - ZZZZ transaction
You can also use wildcards with the TRAN() parameter. For example:
TRAN(A*) TRAN(*99) TRAN(C*99)
Pressing the [Enter] key refreshes the display, pressing the [PF7] key scrolls backward, and pressing the [PF8] key scrolls forward.
The status codes and the thread characteristics they indicate for the DISPLAY TRAN NAME display are:
Table 11-10 Status Codes and Thread Characteristics
Status Code | Thread Characteristic |
---|---|
20 |
reserved |
40 |
use general pool thread (WAIT=POOL) |
80 |
wait for available thread (WAIT=YES) |
The status code can contain more than one meaningful value. For example, a value of 60 (40 + 20) indicates transactions use threads, are running on worker tasks, and if no threads are available, a pool thread is used.
You can display all the active threads used for a particular transaction by entering S to the left of a transaction displayed in the DISPLAY TRAN NAME display:
Pressing the [Enter] key refreshes the display, pressing the [PF7] key scrolls backward, and pressing the [PF8] key scrolls forward.
In this display, the value 1
in the EXEC SQL
column indicates one SQL call has been performed. The columns in this display are:
Table 11-11 Columns in Display
Column | Description |
---|---|
|
thread number |
|
CICS task number |
|
CICS terminal id |
|
program name |
|
number of SQL calls performed |
|
number of SQL commits performed if using ORACLE COMMIT |
|
number of SQL rollback calls performed if using ORACLE ROLLBACK |
|
current error code value |
DISPLAY STATUS NAME displays a screen showing all active threads. An active thread is one currently in use by a CICS TS transaction.
When the command:
ORA2 DISPLAY STATUS NAME(ORA0)
is issued (where ORA2 is the name of the transaction defined to control Oracle Access Manager for CICS TS and ORA0 is the name of the Oracle Access Manager for CICS TS adapter), the screen is displayed
Pressing the [Enter] key refreshes the display, pressing the [PF7] key scrolls backward, and pressing the [PF8] key scrolls forward.
The columns in this display are:
Table 11-12 Columns in Display
Column | Desciption |
---|---|
|
thread number |
|
CICS task number |
|
CICS transaction id |
|
CICS terminal id |
|
program name |
|
thread user's logon id |
|
status code |
The status codes and the thread characteristics they indicate for the DISPLAY STATUS NAME display are:
Table 11-13 Status Codes and Thread Characteristics
Status Code | Thread Characteristic |
---|---|
00 |
no values set |
08 |
reserved |
20 |
high priority thread (for subtasks only, PRIORITY set to HIGH) |
40 |
pool thread |
80 |
protected |
Note:
All the status codes except code 20 apply to the display of both local and remote Oracle data. Status code 20 applies only to local Oracle data.The status code can contain more than one meaningful value. Some codes are not listed and can be ignored because they are for diagnostic purposes.
To purge a transaction or thread from within the DISPLAY STATUS NAME display, enter P to the left of the transaction or thread. You receive one of the following responses indicating the outcome of the purge operation:
This section contains information about START.
START MOD(modname) [MAX(threads) SSN(ssn) NAME(adapter) COMMIT(option)]
where:
Table 11-15 Variable Descriptions for Code Example
This command starts the Oracle Access Manager for CICS TS adapter.
The parameter values specified in the START command override any values specified in the load module named in the MOD parameter.
Because the load module specified in the MOD parameter contains thread definitions, starting the adapter with only the MOD parameter is normally sufficient.
This example provides only the load module and adapter names:
ORA2 START MOD(ORA0) NAME(ORA0)
where:
Table 11-16 Variable Descriptions for Code Example
Variable | Description |
---|---|
|
is the Oracle Access Manager for CICS TS control transaction |
|
is the name of the load module |
|
is the name of the thread definition table. Subsystem name and thread definitions are taken from the |
In this example, an override is specified for the Oracle Access Manager for CICS TS adapter name.
This section contains information about STOR.
STOP NAME(adapter) [IMMEDIATE] [FORCE] [WAIT]
where:
Table 11-17 Variable Descriptions for Code Example
This command stops an Oracle Access Manager for CICS TS adapter started with the START command. When the FORCE option is used with the STOP command, Oracle Access Manager for CICS TS abends all currently running transactions and forcibly shuts down.
This section describes the storage requirements for Oracle Access Manager for CICS TS.
Table 11-18 lists the base code storage requirements for Oracle Access Manager for CICS TS.
Table 11-18 Oracle Access Manager for CICS TS Base Code Storage Requirements for Configuration
Usage | Below 16M | Above 16M |
---|---|---|
ORACICS |
0 bytes |
28K |
CICADPX |
24 bytes |
0K |
LIBCLNTS |
0 bytes |
24MFoot 1 |
Footnote 1 This is above-the-line storage, not managed by CICS TS.
Table 11-19 lists the adapter storage requirements for Oracle Access Manager for CICS TS, which are the same for both the local and remote configurations. The total variable storage requirement per active Oracle server/CICS TS transaction is 30,748 bytes.
The following table displays the Oracle Access Manager for CICS TS adapter storage requirements for local and remote configurations:
Table 11-19 Adapter Storage Requirements for Local and Remote Configurations
Type of Storage | Usage | Area | Below 16M | Above 16M |
---|---|---|---|---|
Fixed |
Per active Access Manager for CICS TS adapter |
Global Exit Area |
1300 bytes |
0 bytes |
Variable |
Per active Oracle Database/CICS TS transaction |
Local Exit Area |
432 bytes |
0 bytes |
For the thread table, a fixed amount of storage is used. This calculation is used to determine a thread table's fixed storage requirements (located above the 16M line):
8176 bytes + (1096 bytes x MAXTHRDS)
Use the same calculation for both the local and remote configurations.
Table 11-20 lists the connected thread storage requirements for Oracle Access Manager for CICS TS.
Table 11-20 Oracle Access Manager for CICS TS Connected Thread Storage Requirements
Type of Storage | Usage | Area | Below 16M | Above 16M |
---|---|---|---|---|
Variable |
Per active Oracle Database/CICS TS connection |
Oracle client storage |
0 bytes |
100K bytesFoot 1 |
Footnote 1 This is above-the-line storage, not managed by CICS TS.
All buffer storage for connected threads under CICS TS release 4.1 or higher is obtained above the 16M line.