This chapter discusses how to configure and operate the Oracle Access Manager for IMS TM. It also describes how the product is integrated with IMS.
The following topics are included:
Oracle Access Manager for IMS TM provides the interface between Oracle Precompiler programs (COBOL, C, or PL/I languages) executing Oracle SQL in an IMS TM transaction, and an Oracle database. Oracle Access Manager for IMS TM communicates with an OSDI local database server or it communicates with a remote Oracle database. The target services, or remote database, is defined in the Resource Translation Table (RTT) discussed in this chapter. Each instance of Oracle Access Manager for IMS TM communicates directly with one OSDI server or one remote database server.
Connections for Oracle IMS transactions, whether to a local or remote database, are created and revised based on criteria defined in the RTT. When the IMS TM transaction requests that work be done in the Oracle database, Oracle Access Manager uses the z/OS Oracle client code, LIBCLNTS, in an LE enclave prepared for this purpose. The Oracle client code communicates with a local Oracle server through cross-memory services or with a remote server through Oracle networking socket calls to satisfy the request. Starting with Oracle9i Release 2, this direct use of socket calls eliminates the requirement for a Net service in earlier releases.
You can run applications built with the following Oracle products for z/OS under Oracle Access Manager for IMS TM:
Pro*COBOL
Pro*C
Pro*PL/1
Refer to Oracle Database User's Guide for IBM z/OS on System z for additional information about using Oracle Precompilers and Oracle Call Interface.
Oracle Access Manager for IMS TM is based on the IMS External Subsystem Attachment Facility (ESAF), a published IMS interface for incorporating external resources into IMS transaction management. ESAF defines program interfaces (exits) that IMS invokes for:
Initialization and connection
Signon and signoff
Thread creation
Synchronization
Termination functions
Some aspects of Oracle Access Manager for IMS TM installation, configuration, and operation are specific to the ESAF architecture. This guide provides some information about ESAF; however, IBM IMS documentation is the definitive source for ESAF information.
Although ESAF is named and discussed as subsystems, Oracle Access Manager for IMS TM does not run as a subsystem in a separate address space. When Oracle Access Manager for IMS TM is configured, IMS region initialization loads the main body of Oracle Access Manager for IMS TM code into the control region and into each dependent region accessing an Oracle database. IMS calls the various ESAF exits under the application management task (dependent regions) or the ESI task (control region). No additional tasks are created by or for Oracle Access Manager for IMS TM. Processing in the control region is primarily for recovery activities. Processing in the dependent region is for Oracle requests issued by transactions running in the region. The control region must connect to Oracle successfully before any dependent region is allowed to connect.
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.
You must install Oracle Database for z/OS including the Oracle Access Manager successfully before you configure the product by:
Placing the main Oracle Access Manager for IMS TM code and supporting modules into the IMS RESLIB or another data set concatenated to RESLIB in the IMS region JCL
Ensuring Oracle Access Manager for IMS TM code and supporting modules are available to STEPLIB or ORAAMIDD and DFSESL DD statements
Installing the linking stub module AMILS (used to link Oracle Access Manager for IMS TM client transaction programs) in a load library accessible to application developers
Placing Oracle Access Manager for IMS TM macros (used to define the product configuration) in an appropriate Assembler language macro source code library
Installing the sample programs and material related to installation verification (this material is not required to configure the product)
These steps are specific to Oracle Access Manager for IMS TM. The installation process can also involve other components of Oracle Database for z/OS or Oracle8i packages.
You must configure an instance of Oracle Access Manager for IMS TM for each distinct Oracle database that is accessed by transactions in an IMS subsystem. IMS (ESAF) requires two identifying characteristics for each instance:
Each is a one-character to four-character identifier you choose. The subsystem identifier is specific to Oracle Access Manager for IMS TM. It is not the subsystem identifier associated with the OSDI subsystem.
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.
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 run time.
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.
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.
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
Oracle Access Manager for IMS TM accommodates these differences by providing a flexible way to determine the Oracle user ID for a given transaction. Oracle user IDs are controlled by parameters generated in the RTT. In the RTT, you can specify the type of Oracle user ID an IMS application can have:
The IMS user ID
For terminal-oriented transactions, this is the signon id if the terminal is signed on. Otherwise it is the IMS LTERM name. For non-message driven batch message processing (BMP), the IMS user ID is one of a hierarchy of choices defined by IMS. In many IMS installations, the IMS user ID is authenticated by RACF or a similar security product.
The IMS program specification program (PSB) name
The IMS PSB name identifies the IMS application.
The application program (load module) name
A specific (constant) Oracle user ID up to 30 characters
This choice makes it possible for Oracle Access Manager for IMS TM to accommodate use of any Oracle user ID.
If you want to replicate the IMS/MVS user ID structure in Oracle, then choose the IMS user ID. You can also choose the IMS PSB name and the application program if they fit your installation. You can specify choices on a PSB-by-PSB basis in the RTT generation, and you can designate a default choice for PSBs not explicitly specified.
An Oracle session created for an IMS transaction using Oracle Access Manager for IMS TM is subject to Oracle's normal authentication mechanisms. These mechanisms are generally controlled by the Oracle database administrator or by system security staff. Oracle supports two kinds of session authentication:
Password authentication requires the client (Oracle Access Manager for IMS TM in this case) to supply a password when establishing an Oracle session for a user ID.
EXTERNAL authentication requires the client interface software to verify the user is already authenticated by the client operating environment.
A given Oracle user ID is subject to one or the other of the authentication mechanisms, as specified by the DBA or security staff in the CREATE USER or ALTER USER SQL statement. In addition to individual user ID specifics, the DBA can specify whether the Oracle instance allows EXTERNAL authentication of sessions coming through Oracle Net. If remote clients (including Oracle Access Manager for IMS TM) are prohibited, then they can use only password-authenticated user IDs.
Without this restriction, Oracle Access Manager for IMS TM supports both forms of authentication. It specifies actual Oracle passwords for user IDs and supports the client mechanics of EXTERNAL authentication when required by the intended Oracle user ID. Oracle Access Manager for IMS TM does not invoke the z/OS SAF/RACF interface to authenticate the user ID before using it with Oracle EXTERNAL authentication. The validity of the user ID is an installation responsibility.
Oracle Access Manager for IMS TM does not automatically know an Oracle user ID authentication mechanism or password. You specify these on a individual user ID basis in the Oracle Access Manager for IMS TM RTT generation. You can provide a default choice for all unspecified user IDs.
Oracle Access Manager for IMS TM does not store Oracle passwords in clear text. Oracle server release 7.1 and above transmits logon data (user ID and possible password) to the target database in encrypted form.
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:
Value | Description |
---|---|
R |
specifies error code associated with the failure are returned to the application program |
Q |
specifies the application program is terminated with an abend code U3044. The input transaction is requeued to be processed when access to the subsystem is restored. |
A |
specifies the application program is terminated with an abend code U3983. The input transaction is discarded. Oracle Access Manager for IMS TM supports all three REO processing options. IMS enables to specify the REO at the region level in the IMS PROCLIB member defining external subsystems. If you omit the REO, IMS assumes a default value of R. |
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.
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.
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.
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.
When IMS starts, if the RTT AMIRT macro CONNECT parameter is set to START, then the control region immediately attempts a connection to the target Oracle server. An Oracle-unavailable condition is detected immediately. On the other hand, if the CONNECT parameter is set to DEFER or defaulted, then the control region waits for the first dependent region to make an Oracle request before attempting its own connection. If the control region is unable to connect to Oracle, then Oracle Access Manager for IMS TM instance is placed in a logical stopped state.
When Oracle Access Manager for IMS TM is in a stopped state after failure of its initial connections, all applications issuing requests for that Oracle Access Manager for IMS TM instance receive a U3049 pseudo-abend and are requeued for later processing. This occurs regardless of the REO option. Even when REO is set to R, an application does not receive an Oracle error when the Oracle Access Manager for IMS TM initial connection attempt fails.
When an Oracle Access Manager for IMS TM instance is placed in the stopped state, it must be started with the IMS command /START SUBSYS after the target Oracle server becomes accessible. This state causes Oracle Access Manager for IMS TM to reinitialize and reattempt a connection to Oracle. If the connection attempt is successful, then queued transactions and new transactions process normally. IMS remembers a subsystem is in stopped state over a warm start. Even if IMS is shutdown and restarted, the /START SUBSYS command is required.
If the Oracle Access Manager for IMS TM initial connection attempt from the control region is successful, then a subsequent loss of access is handled without placing the instance in the stopped state. The failure is likely to be detected during execution of an application making Oracle requests. Application behavior in this case is governed by the REO in effect for the transaction, if coded on the AMITRANS macro, or the region from the SSM entry.
If REO is set to R (or taken as a default), then the Oracle error code associated with the lost connection is returned to the application. Applications that use option R must be careful to check SQLCODE or the return code from an OCI call. If the application fails to detect the error and issues another Oracle request, then a loop between IMS and Oracle Access Manager for IMS TM can result. Refer to the IBM IMS documentation for more information.
With REO set to Q, an application is abended with U3044, requeued, and the transaction is placed in PSTOP status. With option A, the application receives a U3983 abend and the input transaction is discarded. These abends might cause IMS to invoke Oracle Access Manager for IMS TM to resolve in-doubt processing in the control region. This process also fails if Oracle has become unavailable and IMS holds the associated recovery tokens to be processed later.
These circumstances do not place the Oracle Access Manager for IMS TM instance in the stopped state. Instead, Oracle Access Manager for IMS TM remains active and attempts to reestablish a connection to Oracle when another application makes an Oracle request. If the connection attempt is successful, then Oracle Access Manager for IMS TM resumes normal operation. If it fails, then the application is processed according to the REO in effect.
Each attempt to reestablish the connection to Oracle results in some message traffic to the system console or master terminal operator (MTO) console. A high frequency of failing attempts might result in an excessive message load. A RECONTM parameter on the AMIRT macro can specify the MAXIMUM frequency of reconnect attempts in elapsed second terms. The default for RECONTM is 60 seconds: Oracle Access Manager for IMS TM does not attempt to reconnect on behalf of an application if fewer than 60 seconds have passed since the last attempt. If RECONTM is 0, then every application making an Oracle request causes an attempt to reconnect.
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.
Oracle Access Manager for IMS TM must be installed successfully before you can configure it. Refer to Oracle Database Installation Guide for IBM z/OS on System z for more information.
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
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.
Be sure you have read "Integration with IMS" and "Configuration Overview" earlier in this chapter, before beginning the steps in this section.
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 if 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.
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:
Table 12-2 Variable Descriptions for Code Example
Variable | Description |
---|---|
|
is the CSECT name to use for this LIT generation. If the name is omitted, then the name AMILI000 is used by default. If a name is specified, then ensure it does not conflict with external names occurring in transaction programs. Because only one Oracle Access Manager for IMS TM LIT can be linked into an application, it does not matter if the same CSECT name is used in LITs for different Oracle Access Manager for IMS TM instances. |
|
specifies the one-character to four-character LIT. The value can be enclosed in apostrophes. It must conform to IMS ESAF requirements, such as alphanumeric characters. If this parameter is omitted, a LIT value of ORA1 is generated. Assembly of the LIT requires access to the Oracle Access Manager for IMS TM macros. The resulting object code can be linkedited into a load module library or saved as an object deck. It must be included in the linkedit of IMS transaction programs using the associated instance of Oracle Access Manager for IMS TM. The LIT contains no executable code and does not have addressing mode (AMODE) or residency mode (RMODE) limitations. A sample LIT generation job: //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 // |
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 recommends creating a distinct user ID dedicated to this purpose. The user ID must have or be granted these privileges:
No other privileges are required. If you are creating a user ID dedicated to Oracle Access Manager for IMS TM recovery purposes, then Oracle 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 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 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.
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.
Four macros are used to code the RTT:
For a summary of RTT macro parameters governing session cache, refer to "Clarification of Cursor Close Behavior".
The AMIRT macro is invoked once or twice in an RTT definition. The first invocation specifies the connection string for the target Oracle database and other options with subsystem-wide or region-wide scope. The connection string for the target Oracle database is meaningful only in the RTT used by the control region. The address can be omitted in a dependent region RTT. If it is specified, then it must be identical to the one specified for the control region. Otherwise, Oracle Access Manager for IMS TM initialization for the dependent region fails.
The AMIRT macro is coded using this syntax:
[name] AMIRT [DBADDR='string'] [,CONNECT={START|DEFER}] [,RECOID='string'] [,DYNSUBS={YES|NO}] [,ENVTAB=envname] [,END={YES|NO}]
where:
Table 12-3 Variable Descriptions for Code Example
Variable | Description |
---|---|
|
can be any name allowed by the assembler. It is ignored. |
|
specifies the Oracle connection string of the target Oracle database. This string must be a complete address string (not a TNSNAMES alias identifier). Refer to the example in the note at the end of this If accessing a remote database, Oracle Net address strings can be lengthy. You must code continuations of the line on which DBADDR is specified. Remember the assembler normally requires a nonblank continuation indicator in position 72 and the continuation begins in position 16 of the next record. Positions 1-15 must be blank. The easiest way to determine what to specify for an Oracle Net address string is to look in an existing TNSNAMES configuration file. Refer to Chapter 8, "Oracle Net" for more information. Note: The DESCRIPTION keyword is required. For example, for a local database: AMIRT DBADDR='(DESCRIPTION= (ADDRESS=(PROTOCOL=XM)(SID=QA74)))' or, for a remote database: AMIRT DBADDR='(DESCRIPTION=(ADDRESS= (PROTOCOL=TCP) (HOST=144.25.40.217) (PORT=1521) (SSN=TNS)) (CONNECT_DATA=(SID=QA74)))' |
|
specifies whether the region is to establish the connection to Oracle at region startup (START) or wait until the first Oracle access request is made by a transaction program (DEFER). The default is DEFER. This option applies to both control and dependent (MPP) regions. However, the control region is required to establish a connection before any dependent region can connect. CONNECT set to DEFER for the control region serves no purpose if any dependent region immediately uses CONNECT set to START. This parameter is ignored for BMP and IMS fast path (IFP) regions, which always operate with the equivalent of CONNECT set to DEFER. |
|
specifies the Oracle user ID used for IMS recovery activity. During Oracle Access Manager for IMS TM startup processing, the control region accesses Oracle using this id if there are pending uncommitted transactions. An AMISESS macro specifying this id or a default entry allowing this id to logon to Oracle, must be included in the control region RTT. This parameter is ignored in a dependent region RTT. |
|
specifies whether Oracle Access Manager initialization for the control region is permitted to create the Oracle Access Manager subsystem name entry if the name is not defined formally to z/OS. (Refer to the discussion of this topic in "Step 1: Define a z/OS Subsystem Identifier for the Instance".) The default for this parameter is YES. The parameter is ignored in a dependent region RTT. |
|
specifies the name field of an AMIENV macro coded in the same RTT generation. It must conform to Assembler name syntax requirements. The environment variable specifications in the named AMIENV are used in all Oracle Access Manager processing unless overridden by an AMIENV set specified in an AMITRANS or AMISESS macro in this RTT generation. |
|
specifies the end of the RTT definition. When the RTT contains one or more uses of the AMITRANS or AMISESS macros, the AMIRT macro is invoked once at the beginning (where DBADDR is specified) and once at the end with only END set to YES specified. In an RTT definition containing no AMITRANS or AMISESS macros, AMIRT can be invoked a single time with parameters and END set to YES combined. |
The AMITRANS macro assigns characteristics to IMS applications by PSB names. It determines the Oracle user ID that causes a transaction's Oracle access. The Oracle user ID assignment can be a fixed value (for example, SCOTT) or it can be one of three dynamic values associated with the transaction instance. You can assign different PSB names to different user ID determinations. A default determination can be specified for PSB names that do not have an individual entry.
An RTT definition does not need to include AMITRANS macros. The RTT definition assumes a single default user ID determination method for all transactions that run in a region without macros. AMITRANS macros used in an RTT definition, must appear after the first AMIRT macro. AMIRT with END set to YES must also appear at the end of the RTT definition.
The characteristics of one or more individual transactions can be specified in a single use of AMITRANS.
The AMITRANS macro is coded as:
[name] AMITRANS PSB=(psb1,...) ,OID={IMSID|PSB|PGM|'string'} [,REO=c] [,ENVTAB=envname]
where:
Table 12-4 Variable Descriptions for Code Example
Variable | Description |
---|---|
|
can be any name allowed by the assembler. It is ignored. |
|
specifies the IMS PSB names of the applications to which a common set of characteristics are being assigned. A name specification of * designates a default for transactions for which no specific entry is given in any AMITRANS macro. The * can be included on an AMITRANS call also listing specific PSB names. No more than one * entry can be created in a single RTT definition and no specific PSB name can be repeated in an RTT. |
|
specifies the method of determining the Oracle user ID for the transactions listed. The choices are: |
|
is the z/OS and IMS authorization id (or a substitute) used. |
|
is the IMS PSB name used. |
|
is the program name used. |
|
is the fixed character string used. This value can be enclosed in apostrophes. It must be a valid user ID in the target Oracle database and must conform to the content rules for Oracle user IDs. |
|
specifies the IMS region error option used with the associated transactions. This option is coded as a single letter. Permissible values and their meanings are discussed in Error Processing. |
|
specifies the name of an AMIENV macro coded in the same RTT generation. It must conform to Assembler name syntax requirements. The environment variable specifications in the named AMIENV are used in all Oracle Access Manager processing for the indicated transactions. They take precedence over specifications of the same variable in environment tables associated with the AMISESS and AMIRT macros. |
When OID is set to IMSID, determination of the user ID varies with the environment. For message-driven transactions:
Use the RACF-validated signon id if the terminal originating the transaction is signed on.
Use the LTERM id if the terminal is not signed on
In a non-message-driven region:
If the address space is present, use the ASXBUSER field.
If the address space is not present, use the IMS PSB name.
If an RTT contains no AMITRANS macros, the region operates with this default:
AMITRANS PSB=*,OID=IMSID
This statement specifies that all transactions use the MVS/IMS user ID (or a substitute) as the Oracle logon id. If the RTT contains any AMITRANS macros, this default is not assumed. If the RTT contains one or more AMITRANS macros and you also want to specify default transaction characteristics, you must add an AMITRANS for PSB=* or * to the PSB list of an existing AMITRANS macro call in the RTT definition.
The AMISESS macro is used to indicate, by Oracle user ID, the type of logon authentication to use and, if required, the Oracle logon password.
An RTT definition does not need to include any AMISESS macros. In this case, a default set of session characteristics is assumed for all sessions created by the region. If any AMISESS macros are used in an RTT definition, they must appear after the first AMIRT macro. A second use of AMIRT with END set to YES is required at the end of the RTT definition.
The session characteristics of one or more Oracle user IDs can be specified in a single use of AMISESS.
The AMISESS macro is coded as:
[name] AMISESS OID=('string' [,'string'...]) ,AUTH={EXTERNAL|'string'} [,ENVTAB=envname]
where:
Table 12-5 Variable Descriptions for Code Example
Variable | Description |
---|---|
|
can be any name allowed by the assembler. It is ignored. |
|
specifies the Oracle user IDs whose session characteristics are being described. A user ID specification of * designates a default for user IDs for which no specific entry is given. The * can be included on an AMISESS call also listing specific user IDs. No more than one * entry can be created in a single RTT definition. |
|
specifies how the user ID is authenticated at Oracle logon. EXTERNAL indicates Oracle is to assume the user is already authenticated by IMS or z/OS. In this case, no password is sent to Oracle at logon time. Oracle verifies the user ID is known and is created with the IDENTIFIED EXTERNALLY option. If the connection to Oracle is through Oracle Net, the Oracle instance must be configured to allow such connections through Oracle Net. Note: If EXTERNAL is specified, it is important to review the LOGON_AUTH setting in the Database Service definition. The alternative to EXTERNAL is to specify the Oracle logon password. The value specified can be enclosed in apostrophes and must match the Oracle user ID password. Only one password can be specified per AMISESS macro, so an AMISESS macro with more than one OID value associates the same password with all of the user ID. Note: RTT passwords are stored in an encrypted form that can be decrypted. It is the user's responsibility to secure the RTT module, for example, by RACF-protecting the RESLIB library in which the RTT is stored. |
|
specifies the name field of an AMIENV macro coded in the same RTT generation. It must conform to Assembler name syntax requirements. The environment variable specifications in the named AMIENV are used in all Oracle Access Manager processing for the indicated sessions unless overridden at the AMITRANS level. |
If an RTT contains no AMISESS macros, the region operates with this default:
AMISESS OID=*,AUTH=EXTERNAL
This default specifies that all transactions connect to an Oracle instance using the external authentication mechanism. Whatever Oracle user ID that a transaction uses must be known to the target Oracle instance and have the IDENTIFIED EXTERNALLY attribute. If the connection uses Oracle Net, the target Oracle instance must be configured to permit externally authenticated logons through Oracle Net.
If the RTT contains any AMISESS macros, this default is not assumed. If the RTT contains one or more AMISESS macros and you also want to specify default session characteristics, you must add an AMISESS for OID=* or * to the OID list of an existing AMISESS macro call in the RTT definition.
The AMIENV macro defines values for various Oracle software environment variables, particularly NLS support. One AMIENV macro call defines a distinct set of variable name and value pairs. The AMIRT, AMITRANS, and AMISESS ENVTAB parameters allow a given set to be associated at the region, transaction, or session level. When a variable is specified at multiple levels, the order of precedence is AMITRANS, AMISESS, AMIRT.
AMIENV enables to specify any environment variable names. The names and values are not validated during the RTT generation. Do not misspell the name of a variable because AMIENV treats it as though the variable is not specified. An erroneous value for an environment variable becomes apparent at run time when the software attempts to use the value. How the error is reported depends on the variable and specified value.
In the RTT generation, all AMIENV macros must appear after the first AMIRT macro. They can be mixed with AMITRANS and AMISESS macros and, unlike AMITRANS and AMISESS, also can appear after the END set to YES call to AMIRT.
name AMIENV (n1,v1,...)
where:
Table 12-6 Variable Descriptions for Code Example
Variable | Description |
---|---|
|
is a name field conforming to Assembler rules. The name field is required and uniquely identifies the set of variables within the RTT. It is specified as the ENVTAB parameter of an AMIRT, AMITRANS, or AMISESS macro in the RTT. |
|
is an environment variable name, optionally enclosed in apostrophes. Environment variable names used by Oracle products are generally all uppercase. |
|
is the value assigned to the environment variable, optionally enclosed in apostrophes. The apostrophes are required if the value includes characters such as blanks or punctuation that are not part of the Assembler's name syntax. Up to 256 name and value pairs can be specified within the parentheses. A given variable name can appear no more than once in a single AMIENV macro. |
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:
Table 12-7 Variable Descriptions for Code Example
Variable | Description |
---|---|
|
is the IMS system id. |
|
is a one-character to four-character suffix you choose. The suffix is passed to IMS using the SSM startup region parameter. |
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:
Table 12-8 Variable Descriptions for Code Example
Variable | Description |
---|---|
|
is the one-character to four-character subsystem id for this Oracle Access Manager for IMS TM instance. This parameter is required and must begin in the first position of the record. |
|
is the one-character to four-character LIT for this Oracle Access Manager for IMS TM instance. This parameter is required. |
|
is the name of Oracle Access Manager for IMS TM external subsystem module table (ESMT). This parameter is required and must be specified as shown. |
|
is the load module name for the generated Oracle Access Manager for IMS TM RTT. This module is placed in the IMS RESLIB or in a data set concatenated to RESLIB. This parameter is required in the control region SSM and optional in a dependent region SSM. If omitted in a dependent region SSM, the region uses the RTT specified for the control region. |
|
is the region error option, a one-character value specifying how Oracle Access Manager for IMS TM is to handle external subsystem failures during application request processing. It includes the situation where an application issues a request before a connection to the external subsystem can be made. This parameter is optional. If omitted, the IMS default is R. Oracle Access Manager for IMS TM also allows the REO to be specified on a PSB-by-PSB basis in the RTT. The REO specified at the PSB level overrides this REO. The allowed values are:
|
|
is an optional command recognition character. This parameter is not used and can be omitted. |
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 about the coding of the SSM parameter.
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.Authorize the MESG
data set and make the Oracle messages available to the region by performing one of the following actions:
Add the MESG
data set to the STEPLIB concatenation.
Add an ORA$LIB
DD statement for the MESG
data set.
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 about operating the Oracle Access Manager, refer to "Starting and Stopping Oracle Access Manager for IMS TM".
IMS refers to Oracle Access Manager for IMS TM as an external subsystem. IMS requires a z/OS subsystem identifier for each instance of Oracle Access Manager for IMS TM you configure. However, the product does not run as a separate z/OS address space. Instead, the Oracle Access Manager code runs inside the IMS control region and in each dependent region that accesses Oracle data. A separate address space is required for an Oracle Database for z/OS database or for Oracle Net for z/OS. Oracle Database for z/OS or Oracle Net for z/OS is used when running Oracle Access Manager for IMS TM. Refer to Chapter 8, "Oracle Net" for Oracle Net for z/OS operating considerations.
The IMS control region is responsible for monitoring the status of all external subsystems, including all configured instances of Oracle Access Manager for IMS TM. It views each instance as being stopped or started. You can query IMS to determine the status of a subsystem using the IMS operator command DISPLAY SUBSYSTEM. Refer to the IBM IMS documentation for a detailed description of the DISPLAY SUBSYSTEM command.
For example, to request the status of a subsystem with the identifier AMI1, issue the IMS command:
/DIS SUBSYS AMI1
from the IMS master terminal operator (MTO) or z/OS system console. IMS might respond with something like:
DFS000I SUBSYS CRC REGID PROGRAM LTERM STATUS DFS000I AMI1 # NOT CONN
In this example, the Oracle Access Manager for IMS TM instance AMI1
is not currently connected to the target database. If the subsystem is started and active in several regions, then the display might look like:
DFS000I SUBSYS CRC REGID PROGRAM LTERM STATUS DFS000I AMI1 # 1 PRGL08 HN1LN006 CONN DFS000I AMI1 # 3 PRGL15Q HN1LN083 CONN DFS000I AMI1 # 4 PSVB HN0LN19A CONN DFS000I AMI1 # 12 PRGNQ HN1LN072 CONN DFS000I AMI1 # 14 PBNC2UP CONN
Although Oracle Access Manager for IMS TM does not have a display command, it does display status messages under circumstances such as:
Startup
Termination
Recovery activities
Errors
These messages always begin with the prefix AMI- followed by a unique message number. The complete set of Oracle Access Manager for IMS TM messages are documented in the Oracle Database Messages Guide for IBM z/OS.
All Oracle Access Manager for IMS TM messages are written to the operator console and the MTO.
When the IMS control region is started, IMS attempts to initialize all external subsystems configured for that region. This means initializing all external subsystems the IMS subsystem can access. Dependent regions can initialize fewer or even no subsystems, depending on how they are configured.
Initialization of Oracle Access Manager for IMS TM in a given region validates configuration data and allocates virtual memory for required data structures. It does not necessarily attempt to make a connection to the target Oracle server. An Oracle Access Manager for IMS TM configuration option can specify connection to the server be deferred until an IMS application makes a request for Oracle data. This option can be set on a region-by-region basis.
There are connection dependencies. IMS requires the control region establish a connection before any dependent region connection is allowed. If the deferred connection option is used for the control region but a dependent region starting immediately does not defer connection, then the control region is forced to connect immediately.
Regardless of whether connection is made immediately or deferred until the first Oracle request, there are a variety of reasons why the Oracle Access Manager for IMS TM connection process might fail. The target Oracle server might be down. If the target server is remote, then any of a number of required components, such as Oracle Net for z/OS, networking software or hardware, or Oracle Net on the target platform, might be down.
If the connection process fails, then Oracle Access Manager for IMS TM displays error information and informs IMS. IMS places the subsystem in the logical stopped state. If the connection is deferred and is associated with an application request for data, then IMS terminates and requeues the requesting transaction.
When Oracle Access Manager for IMS TM connection fails and the subsystem is stopped, it remains so until the operator issues IMS command START SUBSYSTEM.
Oracle Access Manager for IMS TM does not automatically notify IMS to start when the cause of connection failure is resolved. When the START SUBSYSTEM command is issued, Oracle Access Manager for IMS TM reinitializes in each region. Connection to the target Oracle server is attempted or deferred as indicated in configuration data, just as in the original region startup.
Normal IMS and Oracle Access Manager processing can be interrupted by a failure of any of the hardware and software components involved. Because Oracle Access Manager for IMS TM supports IMS two-phase commit synchronization, active transactions at the time of a failure are one of the following:
Completely committed
Completely rolled back
Left in a recoverable state called in-doubt
When problems are rectified and normal IMS and Oracle Access Manager for IMS TM processing resumes, the IMS control region performs a resolve in-doubt process. This process determines the status of each in-doubt transaction and commits it or rolls it back accordingly. Oracle Access Manager for IMS TM displays messages during this process, indicating the action taken with each in-doubt transaction.
IMS also performs resolve in-doubt processing any time an application abnormally terminates. Therefore, the same messages can be expected after an abend in a transaction using Oracle Access Manager for IMS TM.
From the Oracle server side, transaction activity from Oracle Access Manager for IMS TM falls into the same general class as Oracle distributed transactions. The same internal Oracle tables and views record the status of all such transactions. Transactions that originated in Oracle Access Manager for IMS TM can be identified by their parent database id. Oracle Access Manager for IMS TM constructs a parent database id using a combination of the IMS id and the Oracle Access Manager for IMS TM subsystem id. Detailed information about these tables and views can be found in Oracle Database Reference.
This section describes the storage requirements for Oracle Access Manager for IMS TM.
Table 12-9 lists the base code storage requirements for Oracle Access Manager for IMS TM.
Table 12-10 lists the control region adapter storage requirements for Oracle Access Manager for IMS TM.
Table 12-10 Access Manager for IMS TM Adapter Storage Requirements, Control Region
Control Region | Storage |
---|---|
ORAAMSD |
14K |
LIBCLNTS |
28M |
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.
Table 12-11 Access Manager for IMS TM Adapter Storage Requirements, Dependent Region
Dependent Region | Storage |
---|---|
ORAAMSD |
14K |
LIBCLNTS |
28M |
Oracle Client storage |
100K |
All dependent region allocations are extended private (above 16M).