Oracle9i Enterprise Edition System Administration Guide
Release 2 (9.2.0.1.0) for OS/390

Part Number A97313-01
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

11
Oracle Access Manager for CICS

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

Overview

Oracle Access Manager for CICS 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 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 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 region.

Connections for Oracle CICS 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 transaction the first time that it accesses Oracle.

When the CICS transaction request requires work to be done in the Oracle database, processing is switched to a CICS 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.

Oracle Access Manager for CICS Applications

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

Oracle Access Manager for CICS Configuration

The following figure shows the relationship between an application program and Oracle Access Manager for CICS.

Figure 11-1 CICS Adapter for an Application Program


Text description of am4cics.gif follows
Text description of the illustration am4cics.gif

In the figure, ORA0 is the example adapter name. It is assigned on the CICS side when Oracle Access Manager for CICS is started. Refer to "Step 8:  Start Oracle Access Manager for CICS 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" for details on generating an ORACSTUB stub.

Configuration Checklist

Oracle Access Manager for CICS must be installed successfully before you can configure it. Refer to the Oracle9i Enterprise Edition Installation Guide for OS/390, for more information.

Configuration Steps

Step 1:  Define and Assemble Thread Definition Table

Step 2:  Define the MESG Library to CICS

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

Step 4:  Define CICS to Oracle and Grant Privileges

Step 5:  Set INITORA Parameter and Prepare Host

Step 6:  Generate the ORACSTUB Stub for CICS

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

Step 8:  Start Oracle Access Manager for CICS Adapter

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

Post-Configuration Steps

Step 1:  Modify the Sample Compilation Procedures

Step 2:  Use the SRCLIB Member OSAMPLE

Configuration Steps

Step 1:  Define and Assemble Thread Definition Table

A table, defined and assembled as a load module, defines threads and their characteristics to Oracle Access Manager for CICS. When you create the thread definition table, configure the threads to match the expected workload and priorities for Oracle Access Manager for CICS users and applications.

A thread represents a connection to the database. It is maintained by Oracle Access Manager for CICS. All active CICS transactions that communicate with an Oracle server database use a thread.


Note:

The thread table must be reassembled for the current release of Oracle Access Manager for CICS. 


Before defining your table, select a table name appropriate for your installation. The table name is specified to Oracle Access Manager for CICS at startup in the Oracle Access Manager for CICS 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.

Step 1.1:  Determine the Requirements for Each Transaction

Consider these criteria in determining the requirements for each transaction:

Step 1.2:  Define the Thread Requirements in the Thread Definition Table

When you define a thread table:

Thread Definition Table Parameters

This list describes the thread definition table parameters:

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.

A maximum of three values can be specified for AUTH. Valid values are:  

 

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. The implied Oracle user id is derived by prefixing 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. OPS$ will not be prefixed to this string.

For example, by specifying AUTH='SCOTT', OPS$SCOTT is used as the Oracle user id. 

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

COPIES

indicates the number of threads this definition generates.

DESC

defines the OS/390 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. 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 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 subtasks are run at a higher dispatching priority. If LOW is specified, then Oracle Access Manager for CICS 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 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 OS/390 route code to use when writing messages to the OS/390 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.

TYPE 

is a parameter specifying the type of entry being defined. Valid values are: 

 

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. 

 

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. Refer to "Step 9.1:  Generate 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. Refer to "Step 9.2:  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.  

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.

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 


Note:

To use an explicit Oracle id for the control thread, use the AM4COID and AM4CAUTH parameters on the TYPE=START. To define threads to use an explicit Oracle id, use the OID and AUTH parameters on the TYPE=THREAD entry. 


Special Considerations

These conditions apply to thread table definitions:

Step 1.3:  Assemble and Link Thread Table

  1. Assemble and link the table using one of the following methods.


    Note:

    If you are configuring Oracle Access Manager for both local and remote access, then you must assemble the remote thread table with a different name than the local thread table.  


  2. Assemble the table for database access. The sample JCL in SRCLIB library member TBLJCLN assembles and links the input table.

    Oracle Net allows variable block TNSNAMES files. Oracle Access Manager requires fixed block of 80. In addition, Oracle Net allows free format. Oracle Access Manager must have its entry as the only entry and cannot have any extra spaces.

    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:

    ORA0=
         (DESCRIPTION=
          (ADDRESS=
          (PROTOCOL=TCP)
          (HOST=HQUNIX)
          (PORT=1533)
          (CONNECT_DATA=
          (SID=O803)))
    

    For a local database, the specification might be similar to:

    ORA0=
         (DESCRIPTION=
          (ADDRESS=
          (PROTOCOL=xm)
          (SID=ORA0)))
    

    "OSDI Listener Filenames" also contains a description of TNSNAMES.

    In the SYSLMOD DD statement, specify the name of the data set where the table load module resides.

Step 1.4:  Installing a Revised Thread Table with CICS Executing

If you want to install a revised thread table while CICS 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 using the CEDA command:

    CEDA DEFINE PROGRAM(tablename) LANG(ASSEMBLER) GROUP(groupname) 
    

    where:

    tablename

    is the name of your thread definition table.

    groupname

    is the name of the group, typically ORACLE.

  4. Issue the CICS 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
    
  5. Issue the START command for the adapter.

Step 2:  Define the MESG Library to CICS

You can make the MESG Library available to CICS in one of two ways:

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

Step 4:  Define CICS to Oracle and Grant Privileges

Oracle Access Manager for CICS establishes a database connection at startup

You must define Oracle Access Manager for CICS as an Oracle user by one of the following methods:

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

Step 5:  Set INITORA Parameter and Prepare Host

You must complete the following steps on the server for Oracle Access Manager for CICS. For additional information, refer to the Oracle server installation documentation.

Step 5.1:  Set DISTRIBUTED_TRANSACTIONS

Set the INITORA parameter DISTRIBUTED_TRANSACTIONS to a value equal to or greater than the number of concurrently executing Oracle transactions under CICS. Consider other distributed transactions that are executing concurrently under the Oracle server when setting this value.

If you are using the default Oracle user id for the control thread (the CICS applid), then you must perform the following:

Step 5.2:  Set REMOTE_OS_AUTHENT_TRUE

If you are preparing a remote host for Oracle Access Manager for CICS, and if OS authenticated logon is being used, then set the INITORA parameter REMOTE_OS_AUTHENT to TRUE on the remote database.

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 to Oracle and Grant Privileges".

Step 6:  Generate the ORACSTUB Stub for CICS

To generate the ORACSTUB stub for CICS:

  1. Determine your CICS adapter name.

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

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

  4. Relink your Oracle Precompiler and OCI 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:

    You must regenerate the stub for CICS and relink applications with the new stub. Use of an older stub will result in an ORAP application abend. 


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

If you are running CICS release 2.2 or less, then complete Steps 7.1 through 7.3.

If you are running CICS 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 Adapter".

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

Before you can use Oracle Access Manager for CICS, 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 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.

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

Once you have specified the programs, define the Oracle Access Manager for CICS 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. 


Step 7.3:  Install Oracle Access Manager for CICS 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)

Step 8:  Start Oracle Access Manager for CICS Adapter

To make Oracle Access Manager for CICS available to CICS transactions, you must start the Oracle Access Manager for CICS adapter. An adapter is a CICS program that interfaces between transactions and a system such as Oracle. To start the adapter, you can use:

transaction START MOD(module) 

where:

module

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

transaction

is the Oracle Access Manager for CICS 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 and Oracle is successfully established.

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

If you want to initialize Oracle Access Manager for CICS automatically at CICS initialization time and automatically shutdown Oracle Access Manager for CICS at CICS termination, then the Oracle Access Manager for CICS control program must be invoked during CICS startup and shutdown. This step is optional. These steps describe how to generate the control program with the ORACICS macro.

Step 9.1:  Generate the PLTPI Program

The ORACICS macro generates a command level CICS program that is added to the CICS PLTPI table for automatic initialization during CICS 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 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 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=oran.orav.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=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=oran.orav.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              
/* 

Step 9.2:  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 control program and ORA0 is the name of the CICS 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 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=oran.orav.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=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=oran.orav.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           
/* 

Step 9.3:  Input PLTSD and PLTPI to the CICS DFHEITAL Procedure

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

Step 9.4:  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 with a CEDA DEFINE command. The generated program can be modified to include override parameters.

For CICS release 3.1.1, this program must be placed after PROGRAM=DFHDELIM in the CICS PLTPI table.

Step 9.5:  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 with a CEDA DEFINE command.

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

Post-Configuration Steps

The following steps are optional.

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.

CICSPCCC

for IBM SAA AD/Cycle COBOL/370 programs

CICSPCC2

for VS COBOL II programs

CICSPCCI

for IBM C/370 programs

CICSPCCS

for SAS/C programs

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", 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 by using standard RDO procedures.

  6. Define a transaction to CICS (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, you can invoke the transaction.

Multiple Versions in the Same CICS Region

Multiple versions of Oracle Access Manager for CICS can coexist in the same CICS region as long as the release levels are compatible. For example, release 9.0.1 could co-exist with another release 9.0.x version but not with a release 8.1.x version.

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 9.2.0 version. This will be linked with applications programs accessing the 9.2.0 version.

  2. This version uses the ORACICS load module. Both versions have an ORACICN 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, associating this transaction with the ORACICS program.

Recovery Considerations

Resource recovery is determined by whether COMMIT (CICS) or COMMIT (Oracle) was designated to Oracle Access Manager for CICS as the recovery choice in the thread definition table parameter COMMIT.

Using COMMIT (CICS)

CICS 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 transaction syncpoints explicitly by issuing an EXEC CICS SYNCPOINT or implicitly at transaction end, Oracle Access Manager for CICS 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.

An Oracle error occurs if you specify the CICS option and an Oracle EXEC SQL COMMIT or EXEC SQL ROLLBACK is issued.

Using COMMIT (Oracle)

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

Two-Phase Commit Processing under CICS

When CICS syncpoint processing is selected as the resource commit or recovery choice, Oracle Access Manager for CICS can participate in two-phase commit processing under CICS.

CICS serves as the coordinator and Oracle Access Manager for CICS uses the two-phase commit protocol to interface with the Oracle server.

This process is transparent to the transaction. Oracle Access Manager for CICS 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:

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. Oracle Access Manager for CICS communicates with the Oracle server Sand returns one of three responses to the CICS syncpoint manager:

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.

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. Oracle Access Manager for CICS 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 Warm or Emergency Restart

In this case, CICS has access to a log of in-doubt LUWs. When Oracle Access Manager for CICS starts, it resynchronizes with CICS 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 recoverable resources can be lost in the case of a CICS cold start and might require manual resolution.

Oracle Server Restart

When Oracle Access Manager for CICS detects an Oracle server restart, it resynchronizes in-doubt Oracle server LUWs with CICS and communicates with the Oracle server to complete two-phase commit processing.

Manual Recovery

Oracle in-doubt CICS transactions should not be manually committed or rolled back using the FORCE command. However, some situations, such as a CICS 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 transactions is the concatenation of these fields in the order shown:

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

logical unit of work

is eight characters and represents the value of the logical unit of work obtained form CICS.

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 Oracle9i Database Administrator's Guide.

Shutting Down Oracle Access Manager for CICS with FORCE

To shut down Oracle Access Manager for CICS 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 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 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 automatically restarts and resynchronizes any in-doubt logical units of work. If you start Oracle Access Manager for CICS before the Oracle server, then you must perform the initial start of Oracle Access Manager for CICS manually.

CEDF Support

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
You must be running Oracle Access Manager for CICS Version 4.1 or higher 
to use the Execution Diagnostic Facility.

Oracle Access Manager for CICS Command Usage

Oracle Access Manager for CICS commands are entered with the transaction id followed by the Oracle Access Manager for CICS command. The general format is:

trans_id command parms

where:

trans_id

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

command

is the Oracle Access Manager for CICS command.

parms

is one or more parameters for the command.

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

DISPLAY

Options

DISPLAY NAME, DISPLAY TRAN NAME, DISPLAY STATUS NAME

Syntax

DISPLAY NAME(adapter)
DISPLAY TRAN NAME(adapter)
DISPLAY STATUS NAME(adapter)

where adapter is the name of an Oracle Access Manager for CICS adapter.

Purpose

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

DISPLAY NAME EXAMPLE

DISPLAY NAME displays a screen showing general information about an Oracle Access Manager for CICS 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 and ORA0 is the name of the Oracle Access Manager for CICS adapter), the screen is displayed:

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 and ORA0 is the name of the Oracle Access Manager for CICS 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 status codes and the thread characteristics they indicate for the DISPLAY TRAN NAME display are:

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:

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

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 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 and ORA0 is the name of the Oracle Access Manager for CICS 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:

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:

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:

*

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.  


START

Syntax

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

where:

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 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 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 adapter. If this parameter is not specified, then the modname is used as the name for the CICS 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

Purpose

This command starts the Oracle Access Manager for CICS 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.

START EXAMPLE

This example provides only the load module and adapter names:

ORA2 START MOD(ORA0) NAME(ORA0)

where:

ORA2

is the Oracle Access Manager for CICS 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 adapter name.

STOP

Syntax

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

where:

adapter

is the name of an Oracle Access Manager for CICS 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.

Purpose

This command stops an Oracle Access Manager for CICS adapter started with the START command. When the FORCE option is used with the STOP command, Oracle Access Manager for CICS abends all currently running transactions and forcibly shuts down.

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 control transaction and ORA0 is the Oracle Access Manager for CICS adapter name.


Go to previous page Go to next page
Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Table Of Contents
Contents
Go To Index
Index