11 Oracle Access Manager for CICS TS

11.3.1.1 Configuration Steps

• Step 1: Define and Assemble Thread Definition Table

• Step 2: Define the MESG Library to CICS TS

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

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

• Step 5: Set INITORA Parameter and Prepare Host

• Step 6: Generate the ORACSTUB Stub for CICS TS

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

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

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

11.3.1.2 Post-Configuration Steps

• Step 1: Modify the Sample Compilation Procedures

• Step 2: Use the SRCLIB Member OSAMPLE

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.1 AUTH Thread Definition Table Parameter

A maximum of three values can be specified for AUTH. Valid values are listed in the following table:

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:

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:

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

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

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

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:

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:

The status codes and the thread characteristics they indicate for the DISPLAY STATUS NAME display are:

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:

11.13.2.1 Syntax

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

where:

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:

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

11.13.3.1 Syntax

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

where:

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.