Skip Headers
Oracle® Database System Administration Guide
10g Release 2 (10.2) for IBM z/OS (OS/390)

Part Number B25398-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

11 Oracle Access Manager for CICS TS

This chapter discusses how to configure and operate the Oracle Access Manager for CICS TS. The following topics are included:

11.1 Overview

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 (but not an MPM database server), or it communicates with a remote Oracle database (but not an MPM 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 via cross-memory services or with a remote server via 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.

11.2 Oracle Access Manager for CICS TS Applications

You can run applications built with these Oracle products for z/OS under Oracle Access Manager for CICS TS:

11.3 Oracle Access Manager for CICS TS Configuration

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

CICS TS Adapter for an Application Program
Description of "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 correspondto the adapter name provided at start up of Oracle Access Manager for CICS TS.

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 on 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.

11.4 Configuration Steps

Steps to configure the Oracle Database.

11.4.1 Step 1: Define and Assemble Thread Definition Table

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 prior to 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.

11.4.1.1 Step 1.1: Determine Requirements for Each Transaction

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".

11.4.1.2 Step 1.2: Define Thread Requirements in Thread Definition Table

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.

11.4.2 Thread Definition Table Parameters

The following table contains descriptions of the thread definition table parameters:

Table 11-1 Thread Definition Table Parameters

Parameter Description

AM4COID

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 and requires that at least one thread be defined using the OID and AUTH parameters.

AM4CAUTH

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.

AUTH

determines how the Oracle user id is derived without an explicit connect statement. The Oracle userid 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).

COMMIT

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 the section"Recovery Considerations" for information on these parameter values.

COPIES

indicates the number of threads this definition generates.

DESC

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 var is the name of the environment variable you wish to set, and val is the value you wish to give to var. You can specify several var=val pairs separated by commas in a single ENAME parameter, or a separate TYPE=ENV can be coded for each variable. Do not enclose the names or values in quotes.

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)

FREESPC

defines the amount of free space to be allocated for later additions. This parameter is not implemented.

MAXCRSR

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.

MAXTHRD

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.

NAME

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.

OID

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.

PRIORITY

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.

PROGRAM

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.

PROTECT

specifies whether a thread is protected. Valid values are YES, NO, and nn, where nn is the number of protected threads when used with the COPIES parameter. A value of YES indicates the thread must be protected. (The session is not dropped, even if IDLE TIME has expired.) A value of NO indicates the thread does not need to be protected. NO is the default.

ROUTCDE

defines the z/OS route code to use when writing messages to the z/OS operator console. The default is 11.

SSN

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.

START

specifies the name of the program for CICS PLTPI processing when TYPE is set to PLTPI.

STOP

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.

TRANSAC

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.

WAIT

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.

11.4.2.1 AUTH Thread Definition Table Parameter

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.

TERMID

causes the Oracle user id to be derived from the terminal identification.

TRANSID

causes the Oracle user id to be derived from the transaction id.

USERID

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.


11.4.2.2 TYPE Thread Definition Table Parameter

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

CONTINUE

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.

END

indicates the end of a table.

START

indicates the beginning of the table and sets default values.

THREAD

indicates a thread is being defined.

PLTPI

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.

PLTSD

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.


11.4.2.3 Sample Thread Definition Table

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 

11.4.2.4 Specifying User Authorization

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 userid 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 userid 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 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.

11.4.2.5 Special Considerations

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.

11.4.2.6 Step 1.3: Assemble and Link Thread Table

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.

11.4.2.7 Step 1.4: Installing a Revised Thread Table with CICS TS Executing

If you want to install a revised thread table while CICS TS is executing, then perform these steps:

  1. Ensure that you have reassembled the table as described in "Step 1.3: Assemble and Link Thread Table".

  2. Issue the STOP command for the adapter.

  3. 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

tablename

is the name of your thread definition table.

groupname

is the name of the group, typically ORACLE.


  1. 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
    
    
  2. Issue the START command for the adapter.

11.4.3 Step 2: Define the MESG Library to CICS TS

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.

11.4.4 Step 3: Copy Access Manager for CICS TS Modules to CICS Libraries

  • 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 describedin the section "Client Authorizations".

11.4.5 Step 4: Define CICS TS to Oracle and Grant Privileges

Oracle Access Manager for CICS TS establishes a database connection at startup

  • to perform recovery when CICS syncpoint is used,

  • 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 userid 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 the 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 userid. 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 statements, where userid is the Oracle Access Manager for CICS TS userid from above:

GRANT FORCE ANY TRANSACTION TO userid; 
GRANT SELECT ON SYS.PENDING_TRANS$ TO userid; 
GRANT SELECT ON SYS.PENDING_SESSIONS$ TO userid; 

11.4.6 Step 5: Set INITORA Parameter and Prepare Host

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.

11.4.6.1 Step 5.1: Review IDLE_TIMEOUT Parameter

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.

11.4.6.2 Step 5.2: Set REMOTE_OS_AUTHENT

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.

11.4.6.3 Step 5.3: Set OS_AUTHENT_PREFIX

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".

11.4.7 Step 6: Generate the ORACSTUB Stub for CICS TS

To generate the ORACSTUB stub for CICS TS:

  1. Determine your CICS TS adapter name.

  2. Create the generation statement. Refer to SRCLIB library member ORACSTB for an example.

  3. Generate ORACSTUB. Refer to SRCLIB library member ORACSJCL for an example.

  4. 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.

    Note:

    If you are using an Access Manager for CICS TS stub prior to release 9.2, you must regenerate the stub for CICS TS and relink applications with the new stub. Use of an older stub will result in an ORAP application abend.

11.4.8 Step 7: Update CICS TS Tables to Include Oracle Access Manager for CICS TS

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".

11.4.8.1 Step 7.1: Define Oracle Access Manager for CICS TS Programs to CICS

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.

11.4.8.2 Step 7.2: Define Oracle Access Manager for CICS TS Transactions to CICS

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.

11.4.8.3 Step 7.3:  Install Oracle Access Manager for CICS TS Resources

After you have defined the programs and transactions, install the newly created Oracle group. In this example, the group name is ORACLE. Use this command to install the new group:

CEDA INSTALL GROUP (ORACLE)

11.4.9 Step 8: Start Oracle Access Manager for CICS TS Adapter

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

module

is the name of the assembled thread definition table containing the Oracle Access Manager for CICS TS control transaction.

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.

11.4.10 Step 9: Set Up Automatic Initialization for Oracle Access Manager for CICS TS

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.

11.4.10.1 Step 9.1: Using the CICS TS initialization parameter

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 overide. 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.

11.4.10.2 Step 9.2: Using the PLTPI Program

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 
/* 

11.4.10.3 Step 9.3: Generate the PLTSD Program

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           
/* 

11.4.10.4 Step 9.4: Input PLTSD and PLTPI to the CICS DFHEITAL Procedure

Use the generated assembler language CICS TS command-level programs (PLTSD and PLTPI) as input to the CICS DFHEITAL procedure.

11.4.10.5 Step 9.5: Add the User-Defined Name to the PLTPI Table

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.

11.4.10.6 Step 9.6: Add the User-Defined Name to the PLTSD 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.

11.4.10.7 Step 9.7: Make Generated Programs Available

Ensure the generated programs are available in a library included in the CICS DFHRPL.

While using the PLTPI and PLTSD programs, status messages are issued to the system console.

11.5 Post-Configuration Steps

The following steps are optional.

11.5.1 Step 1: Modify the Sample Compilation Procedures

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.

Table 11-6 Compilation Procedures and Libraries

Procedure Library

CICSPCCC

for COBOL programs

CICSPCCI

for IBM C/370 programs


11.5.2 Step 2: Use the SRCLIB Member OSAMPLE

SRCLIB member OSAMPLE is a COBOL II program that displays an employee name from the EMP table. To use the sample program, you must:

  1. Ensure the EMP table is on the database.

  2. Ensure SCOTT/TIGER is a valid logon id on the database. Also ensure SCOTT /TIGER has access to the EMP table.

  3. Ensure "Step 6: Generate the ORACSTUB Stub for CICS TS", is completed.

  4. 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.

  5. Define the program OSAMPLE to CICS TS by using standard RDO procedures.

  6. Define a transaction to CICS TS (for example, OSAM) using standard RDO procedures and associate it with the OSAMPLE program.

  7. Once the START command is issued for Oracle Access Manager for CICS TS, you can invoke the transaction.

11.6 Multiple Versions in the Same CICS TS Region

This version of Oracle Access Manager for CICS TS can coexist in the same CICS TS region with a version prior to release 9.2. For example, release 10.1 can co-exist with release 9.0.x or earlier, but not with a release 9.2.x.

To configure a second version, perform the following steps:

  1. (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.

  2. This version uses the ORACICS load module. If a prior version uses the ORACICN load module name as distributed, there is no conflict.

  3. Define a second control transaction to CICS TS, associating this transaction with the ORACICS program.

11.7 Recovery Considerations

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.

11.7.1 Using COMMIT (CICS)

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 need to 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.

11.7.2 Using COMMIT (Oracle)

Oracle has its own recovery mechanism, independent of CICS TS, and utilizes 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.

11.8 Two-Phase Commit Processing under CICS TS

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:

11.8.1 First Phase

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

ABORT

indicates the Oracle server could not complete the CICS PREPARE request.

PREPARED

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.

READ-ONLY

indicates no data has been modified so no PREPARE is necessary.


11.8.2 Second Phase

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

11.8.2.1 CICS TS Warm or Emergency Restart

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 in the case of a CICS TS cold start and might require manual resolution.

11.8.2.2 Oracle Server Restart

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.

11.8.2.3 Manual Recovery

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$applid

is the eight character CICS applid, or the value of AM4COID in the thread table.

adapter name

is the four-character name of an Oracle Access Manager for CICS TS adapter.

logical unit of work

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.

11.9 Shutting Down Oracle Access Manager for CICS TS with FORCE

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.

11.10 CEDF Support

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 userid and password information displayed.

SQL statements are displayed as coded; the values for variables are not resolved.

11.11 Oracle Access Manager for CICS TS V$SESSION Information

Oracle Access Manager for CICS TS uses the PL/SQL package dbms_application_info to maintain the following fields in the V$SESSION table. Ssession information is updated for each CICS TS transaction when the database is first accessed:

11.12 Oracle Access Manager for CICS TS Recovery and Autorestart

The following are three scenarios for determining whether Oracle Access Manager for CICS TS will restart automatically or will need to be restarted manually in the event that the database becomes unavailable:

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.

11.13 Oracle Access Manager for CICS TS Command Usage

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

trans_id

is the Oracle Access Manager for CICS TS transaction id (usually ORA2).

command

is the Oracle Access Manager for CICS TS command.

parms

is one or more parameters for the command.


Oracle Access Manager for CICS TS commands can be entered in two ways:

11.13.1 DISPLAY

The following section contains information about DISPLAY.

11.13.1.1 Options

DISPLAY NAME, DISPLAY TRAN NAME, DISPLAY STATUS NAME

11.13.1.2 Syntax

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.

11.13.1.3 Purpose

This command allows you to monitor your Oracle Access Manager for CICS TS system. The screen displayed varies according to which DISPLAY command is issued.

11.13.1.4 DISPLAY NAME Example

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:

11.13.1.5 DISPLAY TRAN NAME Example

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

thread number

TASK

CICS task number

TERM

CICS terminal id

PROGRAM

program name

EXEC SQL

number of SQL calls performed

COMMIT

number of SQL commits performed if using ORACLE COMMIT

ROLLBACK

number of SQL rollback calls performed if using ORACLE ROLLBACK

ERROR

current error code value


11.13.1.6 DISPLAY STATUS NAME Example

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

thread number

TASK

CICS task number

TRAN

CICS transaction id

TERM

CICS terminal id

PROGRAM

program name

LOGONID

thread user's logon id

STATUS

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:

Table 11-14 Outcome of Purge Operation

Response Description

*


indicates the purge was successful.

E

indicates the purge was not successful.

?

indicates the current transaction was completed before the purge was attempted.


Caution:

The purge facility performs cleanup, and issues an ORAP application abend for the transaction.

11.13.2 START

This section contains information about START.

11.13.2.1 Syntax

START MOD(modname) [MAX(threads) SSN(ssn) NAME(adapter) COMMIT(option)]

where:

Table 11-15 Variable Descriptions for Code Example

Variable Description

modname

is the name of the load module for the Oracle Access Manager for CICS thread definition table. If the NAME parameter is not specified, then this is used as the name of the Oracle Access Manager for CICS TS adapter.

threads

is the maximum number of threads supported by this adapter. This overrides the value specified in the ORACICS macro.

ssn

is the name of the Oracle subsystem corresponding to this adapter, if the Oracle Access Manager for CICS TS transaction is accessing local Oracle data. If the transaction is accessing remote Oracle data, then the ssn is the four-character alias name used in the CICS TNSNAMES entry.

adapter

is the name of the CICS TS adapter. If this parameter is not specified, then the modname is used as the name for the CICS TS adapter.

option

is the recovery choice. This overrides the value specified in the ORACICS macro. The two valid values for option are:

CICS to use CICS SYNCPOINT

ORACLE to use Oracle COMMIT/ROLLBACK


11.13.2.2 Purpose

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.

11.13.2.3 START Example

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

ORA2

is the Oracle Access Manager for CICS TS control transaction

ORA0

is the name of the load module

ORA0

is the name of the thread definition table. Subsystem name and thread definitions are taken from the ORA0 table.


In this example, an override is specified for the Oracle Access Manager for CICS TS adapter name.

11.13.3 STOP

This section contains information about STOR.

11.13.3.1 Syntax

STOP NAME(adapter) [IMMEDIATE] [FORCE] [WAIT]

where:

Table 11-17 Variable Descriptions for Code Example

Variable Description

adapter

is the name of an Oracle Access Manager for CICS TS adapter started with the START command.

IMMEDIATE

is an optional parameter that rejects all requests but does not shut down until the system quiesces.

FORCE

is an optional parameter that terminates all threads and shuts down. Any active transactions will receive an ORAP application abend on the next Oracle access. When there are no active Oracle transactions, the adapter will shut down.

WAIT

is an optional parameter that waits for the adapter to shut down before returning control to the terminal.


11.13.3.2 Purpose

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.

11.13.3.3 STOP FORCE Example

This example shows the STOP command with IMMEDIATE FORCE:

ORA2 STOP NAME(ORA0) IMMEDIATE FORCE

where ORA2 is the Oracle Access Manager for CICS TS control transaction and ORA0 is the Oracle Access Manager for CICS TS adapter name.

11.14 Oracle Access Manager for CICS TS Storage Requirements

This section describes the storage requirements for Oracle Access Manager for CICS TS.

11.14.1 Base Code Storage Requirements

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.

11.14.2 Adapter Storage Requirements

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


11.14.3 Thread Table Storage Requirements

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.

11.14.4 Connected Thread Storage Requirements

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.