12 Oracle Access Manager for IMS TM

12.3.1 Oracle Access Manager for IMS TM Design

Oracle Access Manager for IMS TM minimizes resource consumption for processor utilization, memory utilization, and activities that can be serialized. One connection is maintained between an IMS region and a given target Oracle database, regardless of the number of distinct transactions or security contexts (Oracle user ids) the region hosts over time. Oracle Access Manager for IMS TM logically maps the combination of IMS thread and Oracle user id to the generic Oracle server session mechanism. The sessions are created and managed dynamically. They are based on the stream of transactions created by users and configuration parameters set by the installation.

The Oracle Access Manager for IMS TM code runs in 31-bit addressing mode and resides above the 16M address line. All dynamically acquired virtual memory is also above the 16M line. Oracle Access Manager for IMS TM is completely reentrant. If the installation prefers, all IMS regions accessing Oracle databases can share a single copy of the code. Each instance of Oracle Access Manager for IMS TM (that is, each distinct Oracle database to be accessed) requires allocation of less than 4K of global (ECSA) virtual memory.

12.4.1 The LIT and SSM

The LIT is embedded in transaction programs using an instance of Oracle Access Manager for IMS TM. When a transaction program runs, IMS associates its LIT with a given subsystem identifier through an entry in the IMS subsystem parameter file, referred to as an SSM member of IMS PROCLIB. The SSM member is an IMS region parameter file defining each external subsystem that can be accessed from that region.

Different IMS regions can have different SSM members. The control region SSM must specify every external subsystem instance (Oracle Access Manager for IMS TM, DB2 for z/OS, or others) that the IMS subsystem can access. Dependent regions can access any external subsystem defined in the control region SSM by default. To limit the external subsystems available to a dependent region or vary the parameters for one or more subsystems from what is specified for the control region, create a separate SSM for the dependent region. To prevent access to all external subsystems from a region, specify a dummy (empty) SSM. You are responsible for ensuring that each dependent region SSM allows access to the external subsystems required by the transactions scheduled in that region.

12.4.2 Resource Translation Table

IMS designates the data that can be coded in an SSM entry. The few defined parameters are not sufficient for implementation of Oracle Access Manager for IMS TM. The SSM does allow you to specify an additional subsystem parameter module called a resource translation table (RTT) whose contents are not specified by IMS. IMS loads the module during region initialization and passes its address to Oracle Access Manager for IMS TM as part of the ESAF exit interface.

Oracle Access Manager for IMS TM uses the RTT to specify most of its parameters and options. At least one RTT is required for each Oracle Access Manager for IMS TM instance. You generate an RTT by coding S/370 Assembler language macros (examples provided with Oracle Access Manager for IMS TM) that create the needed parameter structures. These structures are queried by Oracle Access Manager for IMS TM at runtime.

Although the RTT is a generic ESAF entity, its contents are specific to the external subsystem being accessed. Therefore, the Oracle RTT bears no resemblance to the one used by DB2, for example, and serves a different purpose.

The installation codes macro parameters that specify:

• The Oracle Net address of the target database

• Characteristics of IMS transactions

• How target database sessions are managed

• Other details

The macro calls are assembled and linked to produce a load module. The load module is placed in (or concatenated to) the IMS RESLIB. The module's name must be specified as the RTT parameter for the Oracle Access Manager for IMS TM instance in the control region SSM. For additional details, refer to "Configuration Steps".

Different RTT modules can be created for the same target Oracle database to vary Oracle Access Manager for IMS TM behavior from region to region. The RTT specified in the control region SSM entry for the database is considered the master RTT. It specifies parameters that cannot be varied among the dependent regions, such as the address of the target Oracle database. All of its parameters apply in dependent regions that do not have a separate RTT. The additional RTT modules are specified in the dependent region SSM.

12.4.3 Distributed Option Considerations

If the target Oracle database does not have the distributed option installed, then IMS transactions are not allowed to update any data in that database.

12.4.4 Security Considerations

Oracle and IMS/MVS security differ in some respects. Oracle database user ids can be up to 30 characters. User ids on z/OS are limited to seven or eight characters. You have a choice of security schemes when creating user ids for Oracle Access Manager for IMS TM. You can:

• Create new Oracle user ids specifically for Oracle Access Manager for IMS TM-based applications

• Replicate the z/OS user ids on the Oracle side and adhere to a single user id view

• Use existing Oracle user ids or schema names that differ from what is being used in z/OS

12.4.5 Error Processing

IMS defines a characteristic called a region error option (REO), which specifies how an ESAF implementation handles non-application processing errors, such as a loss of communications with the external subsystem. The REO has one of three one-character values:

Oracle Access Manager for IMS TM also provides a mechanism so that you can specify the REO at the application level on the basis of PSB name. An REO specified at the PSB level overrides whatever REO is given or defaulted for the region.

12.4.6 Recovery Considerations

ESAF allows automated recovery after an outage by providing a two-phase commit interface for synchronizing updates. It also provides a process for resolving partially-committed (in-doubt) transactions when connections are reestablished. The IMS control region resolves in-doubt transactions with participation of all ESAF-defined external resources.

To support this recovery, an Oracle Access Manager for IMS TM instance establishes a connection from the control region to the target Oracle database and executes functions to forcibly commit or rollback pending transactions as directed by IMS. The Oracle Access Manager for IMS TM RTT generation must specify a valid Oracle user id under which these recovery actions are performed. The user id does not have full DBA privileges, but does require several privileges that are part of the Oracle DBA role. You can create a new Oracle user id for this purpose or use an existing user id with the required privileges. The RTT generation must provide authentication specifications allowing the recovery user id to connect to Oracle.

12.4.7 Clarification of Cursor Close Behavior

The Oracle server's normal behavior leaves cursors open across COMMIT and ROLLBACK operations. You can use the precompiler MODE option to request application behavior closer to current ANSI standards, including closing of cursors on commit or rollback. The Oracle Access Manager for IMS TM supports this behavior and IMS-initiated commit (GU or SYNC) and rollback (ROLL or ROLB). If MODE is set to ANSI or one of its variations is not specified at precompile time, then Oracle cursors remain open across IMS-initiated commit or rollback. However, if the application is defined in the RTT AMITRANS macro as OID=IMSID and the beginning of a new transaction causes a change in the user id, then cursors are closed and database session state is lost before the new transaction begins. A change in Oracle user id forces the current Oracle session to be deleted and a new one created. It is the responsibility of the application to be aware of this condition and act accordingly.

This situation cannot arise if the AMITRANS macro specifies PSB, PGM, or a fixed user id string as the Oracle user id. It also does not occur if the AMITRANS macro has OID set to IMSID and a new transaction does not convey a change of user id, which might occur when the new input message comes from the same user, LTERM, or from a BMP.

12.4.8 Handling Oracle Unavailable Situations

Oracle unavailable refers to any situation in which the Oracle Access Manager for IMS TM cannot access the target Oracle server. This situation might result from shutdown or failure of a variety of system components including:

• The target Oracle instance

• Oracle Net for z/OS or a specific protocol adapter

• Other network software (for example, TCP/IP, VTAM)

• Physical network components (routers, for example)

• Remote Oracle Net listener

Oracle Access Manager for IMS TM makes no operational distinction among these situations. It recognizes Oracle is unavailable, perhaps temporarily. There is a difference, however, in whether the condition is detected on the Oracle Access Manager for IMS TM initial connection attempt versus a loss of Oracle access after normal connections are established.

12.4.9 Oracle Environment Variables

Environmental variables control aspects of Oracle product behavior. Environment variables are distinctly-named parameters, set by a mechanism external to the product. Oracle NLS support relies on environment variables to determine the user's preferred message language, character set encoding, and other locale-sensitive attributes.

In a non-IMS batch job or TSO session, the Oracle Database for z/OS products read a sequential file containing environment variable settings. However, IMS environments prefer different environment variable settings from one transaction to the next in the same region. Sequential file processing might negatively affect performance. Oracle Access Manager for IMS TM specifies environment variables in the RTT generation.

Environment variables are defined in groups in the RTT. Each group is associated with specific transactions (PSBs), specific Oracle user ids, or with the RTT as a whole by coding the group name on the transaction, session, or main RTT definition macros. When an Oracle software component requests the value for a particular variable, Oracle Access Manager for IMS TM checks environment variable groups for:

• Current transaction definition

• Current session definition

• RTT default

These groups are checked in this order to locate a value. The transaction-level specification of a variable has highest priority, followed by a session-level specification, followed by the RTT default.

It is not necessary to provide environment variable definitions at any level if the normal Oracle Database for z/OS defaults are acceptable. The Oracle Access Manager environment does not use the CONNSTR variable, and all variables whose names begin with CRTL_. If these variables are specified, then they are ignored.

12.5.1 Oracle Access Manager for IMS TM Configuration Checklist

• Step 1: Define a z/OS Subsystem Identifier for the Instance

• Step 2: Choose a Value for the Instance and Generate the LIT

• Step 3: Create a User Id in the Target Oracle Database Used to Conduct Recovery

• Step 4: Determine the Oracle User Id, Authentication, and Environment Variable

• Step 5: Code and Generate the Control Region and Dependent Region RTT

• Step 6: Add a Control Region and Dependent Region SSM Entry for the Instance

• Step 7: If a New SSM Member is Created for Any Region, Specify the Member to IMS

• Step 8: Make the Oracle Access Manager Code and Modules Available to IMS Regions

• Step 9: Shutdown and Restart IMS

When IMS is restarted, the control region reports the status of Oracle Access Manager for IMS TM initialization. The control region automatically initializes Oracle Access Manager for IMS TM in the dependent regions used. Actual connection to the target Oracle database might occur, depending on options specified in the RTT (for example, one option is to defer connection until a transaction actually issues an Oracle request). Transaction programs prepared for use with Oracle Access Manager for IMS TM can execute.

12.6.1 Step 1: Define a z/OS Subsystem Identifier for the Instance

Oracle Access Manager for IMS TM requires a z/OS subsystem id. The id is used as part of an internal communication mechanism. Any valid one-character to four-character subsystem id known to z/OS can be used as long as it is not used by another subsystem or another instance of Oracle Access Manager for IMS TM.

An IPL normally is required to add new subsystem identifiers to z/OS. However, if the subsystem name you assign is not formally defined, Oracle Access Manager for IMS TM dynamically creates its own entry on the z/OS subsystem control table (SSCT) chain. It creates the entry by using RTT macro AMIRT DYNSUBS set to YES, which is the default. This entry allows the product to be configured and used without requiring a z/OS IPL. The interface for adding an SSCT entry is not a published z/OS interface. If you prefer, you can specify that Oracle Access Manager for IMS TM is not to dynamically create its own SSCT. This is done by specifying the RTT macro AMIRT DYNSUBS be set to NO. In this case, Oracle Access Manager for IMS TM is not able to run until the subsystem name is added and z/OS is re-IPLed.

12.6.2 Step 2: Choose a Value for the Instance and Generate the LIT

The LIT is a four-character identifier. It is generated using an Assembler language macro (AMILI) and embedded at linkedit time in each IMS transaction program using the associated instance of Oracle Access Manager for IMS TM. The LIT you choose must be unique within the IMS subsystem. It cannot duplicate the LIT of another Oracle Access Manager for IMS TM instance or the LITs associated with other external resources.

The LIT can be identical to the subsystem id. However, an identical LIT can cause problems if you expect to vary the LIT subsystem configuration in the future. For example, if you change the SSM so an existing LIT is associated with a new subsystem, the new LIT might be confused with the old subsystem identifier.

LIT generation is performed by coding and assembling an AMILI macro instruction as follows:

[name]    AMILI [LIT=lit]

where:

//AMILIT1 JOB (ORA),'ORACLE LIT GEN'
//  EXEC ASMCL,PARM.LKED='LIST,RMODE=ANY'
//ASM.SYSLIB  DD DSN=ORACLE.V10G.MACLIB,
//            DISP=SHR
//ASM.SYSIN    DD *
ORA3LIT  AMILI LIT=ORA3
         END
/*
//LKED.SYSLMOD DD DSN=IMS1.DEV.LIB(ORA3LIT),
//           DISP=SHR
//

12.6.3 Step 3: Create a User Id in the Target Oracle Database Used to Conduct Recovery

Oracle Access Manager for IMS TM requires a user id in the target Oracle database so recovery sessions can be established when needed by the control region. Although you can use an existing Oracle user id with the appropriate privileges, Oracle Corporation recommends creating a distinct user id dedicated to this purpose. The user id must have or be granted these privileges:

• CREATE SESSION (system privilege)

• FORCE ANY TRANSACTION (system privilege)

• SELECT ON SYS.PENDING_SESSIONS$ (object privilege)

• SELECT ON SYS.PENDING_TRANS$ (object privilege)

No other privileges are required. If you are creating a user id dedicated to Oracle Access Manager for IMS TM recovery purposes, then Oracle Corporation recommends only these privileges be granted to the user id.

The recovery user id does not create data in the target database. Therefore, RESOURCE privileges and user id tablespace defaults and quotas are unimportant. The user id profile is important because the recovery user id must not be subject to Oracle resource limits that could cause an interruption of recovery activity. Such activity includes the profile IDLE_TIME limit because the recovery session can stand idle for a long time.

The authentication method for the recovery user id can be password or EXTERNAL. When creating a new user id, choose an authentication method based on your Oracle and IMS security practices. The recovery user id is coded explicitly in the RTT; it is not derived from an RTT transaction specification. The control region RTT must contain a session authentication entry allowing the recovery id to connect successfully to Oracle. This entry can be the default session entry if the default authentication method applies to the recovery id. If it does not, an explicit session entry for the recovery user id must be included in the RTT.

If you plan to access a particular Oracle database from more than one IMS subsystem, all IMS subsystems can use the same recovery user, assuming the user id's profile allows at least one session per IMS. However, Oracle Corporation recommends you create a distinct recovery user id for each distinct IMS subsystem. This allows better activity tracking in the Oracle server and simplifies problem resolution.

SQL statements for creating a recovery user id are shown in the following example. They are suitable for use in a Server Manager or SQL*Plus session:

CONNECT SYS/CHANGE_ON_INSTALL
CREATE USER IMS1RECO IDENTIFIED BY RECO1PW PROFILE NO_LIMIT;
GRANT CREATE SESSION, FORCE ANY TRANSACTION TO IMS1RECO;
GRANT SELECT ON PENDING_SESSIONS$ TO IMS1RECO;
GRANT SELECT ON PENDING_TRANS$ TO IMS1RECO;

The example assumes a profile named NO_LIMIT is already defined to Oracle. The GRANT SELECT statements specify unqualified table names because the connection is with user id SYS, which owns the PENDING_TRANS$ and PENDING_SESSIONS$ tables.

12.6.4 Step 4: Determine the Oracle User Id, Authentication, and Environment Variable

Review the transaction programs you plan to run with this Oracle Access Manager for IMS TM instance to choose the method for determining the Oracle user id for each transaction. When you know what Oracle user ids to use, establish the authentication method for their Oracle sessions. If you are creating new Oracle user ids for Oracle Access Manager for IMS TM applications, you can choose whichever authentication method is appropriate for your installation's security practices.

Finally, consider the user and transaction management requirements to determine environment variable settings at the RTT, session, and transaction level.

12.6.5 Step 5: Code and Generate the Control Region and Dependent Region RTT

Four macros are used to code the RTT:

• AMIRT

• AMITRANS

• AMISESS

• AMIENV

For a summary of RTT macro parameters governing session cache, refer to "Clarification of Cursor Close Behavior".

[name] AMIRT [DBADDR='string']
[CONNECT={START|DEFER}]
[RECOID='string']
[DYNSUBS={YES|NO}]
[ENVTAB=envname]
[END={YES|NO}]

AMIRT DBADDR='(DESCRIPTION=
(ADDRESS=(PROTOCOL=XM)(SID=QA74)))'

AMIRT  DBADDR='(DESCRIPTION=(ADDRESS=
(PROTOCOL=TCP) (HOST=144.25.40.217)  (PORT=1521) (SSN=TNS))  (CONNECT_DATA=(SID=QA74)))'

[name]   AMITRANS  PSB=(psb1,...)
           OID={IMSID|PSB|PGM|'string'}
                         [REO=c]
                                                 [ENVTAB=envname]

AMITRANS PSB=*,OID=IMSID

[name]       AMISESS  OID=('string' [,'string'...])
    AUTH={EXTERNAL|'string'}
    [ENVTAB=envname]

AMISESS OID=*,AUTH=EXTERNAL

name  AMIENV (n1,v1,...)

12.6.6 Step 6: Add a Control Region and Dependent Region SSM Entry for the Instance

If you access external subsystems from IMS, then you already have an SSM parameter file. If not, you must create one. The parameter file is a member of the IMS PROCLIB data set. Its member name is in the form:

imsidSSM_suffix 

where:

IMS TM Version 4.1 introduces a new keyword syntax for SSM entries. This syntax is not supported by Oracle Access Manager for IMS TM. You must code the SSM entry using IMS/DC Version 3.1 positional syntax, which is accepted by both IMS versions.

An Oracle Access Manager for IMS TM entry in the parameter file such as IMSLORA0, is a single logical record:

ssn,lit,ORAESSD,rtt,reo,crc

where:

12.6.7 Step 7: If a New SSM Member is Created for Any Region, Specify the Member to IMS

If in Step 6 you created a new SSM member, you must specify the member to IMS. Both the control and dependent regions use the SSM keyword parameter for this purpose. The value for the parameter is the one-character to four-character SSM_suffix discussed in Step 6.

The SSM parameter can be specified in the execute procedures for the control region or dependent regions and can be specified in the JCL for batch message processing jobs. For IMS Version 4 or higher, it can be included in the operator command for /START SUBSYS. Refer to the IBM document IMS System Definition and Tailoring for more information on the coding of the SSM parameter.

12.6.8 Step 8: Make the Oracle Access Manager Code and Modules Available to IMS Regions

Access Manager for IMS uses modules from an ORAAMIDD DD statement, if present in IMS jcl. This is an alternative for placing authorized modules in the STEPLIB concatenation. The generated RTTs must be available in a data set that is part of STEPLIB or ORAAMIDD and DFSESL.

Copy the following modules into an authorized library that is part of each region's STEPLIB or ORAAMIDD and DFSESL concatenation:

• ORAAMSD (external subsystem code, copy from AUTHLOAD)

• ORAESSD (external subsystem table, copy from AUTHLOAD)

• AMIUS (ami messages, from MESG data set)

  Note:

  The Oracle AUTHLOAD cannot be used in the DFSESL concatenation because IMS does not support PDSE format in DFSESL.

Copy the following modules from CMDLOAD into an authorized library that is a part of each region's STEPLIB concatenation or ORAAMIDD:

• LIBCLNTS (shared client code)

• AMIMAIN (IMS client interface code)

• AMIDMYC (bootstrap program)

  Note:

  This library must be in PDSE format and should not be put in the DFSESL concatenation.

Make the Oracle messages available to the region by performing one of the following actions:

• Authorize the MESG data set and add it to the STEPLIB concatenation.

• Add an ORA$LIB DD statement for the MESG data set.

12.6.9 Step 9: Shutdown and Restart IMS

When appropriate, follow your installation's normal procedure to shutdown and restart the IMS subsystem. You can use a warm start or cold start.

If your configuration is successful, you see message AMI-0108 displayed at the IMS MTO console once for each region that is permitted to access the new Oracle Access Manager instance. If the RTT for a region specifies CONNECT set to START (on the AMIRT macro), you also see message AMI-0113 indicating a connection is established to the target Oracle instance. Otherwise, IMS delays the connection attempt until a transaction issues a request.

If the connection attempt fails for any reason, an error message is displayed and IMS places the Oracle Access Manager instance in a stopped state. Once you have corrected the problem, you can restart the Oracle Access Manager instance by issuing the IMS /START SUBSYS ssn command.

For more information on operating the Oracle Access Manager, refer to "Starting and Stopping Oracle Access Manager for IMS TM".

12.10.1 Base Code Storage Requirements

Table 12-9 lists the base code storage requirements for Oracle Access Manager for IMS TM.

All CSA allocations are ECSA (above 16M).

12.10.2 Adapter Storage Requirements

Table 12-10 lists the control region adapter storage requirements for Oracle Access Manager for IMS TM.

All control region allocations are extended private (above 16M).

Table 12-11 lists the dependent region adapter storage requirements for Oracle Access Manager for IMS TM.

All dependent region allocations are extended private (above 16M).