Setting up TXSeries with Oracle on Windows

Setting up TXSeries with Oracle on Windows describes how you can enable the region to connect to an Oracle database.

1. Prepare the resource manager (RM)
   1. Enable connections between CICS and RM

      Oracle sets the environment variable TCL_LIBRARY in the system environment, which can cause errors with the cicscp command. After installing Oracle, move this environment variable from the system environment to any user environment that will be used for Oracle administration.

      Note: Any environment that has the TCL_LIBRARY environment variable set to point to the Oracle-supplied TCL library cannot be used for CICS administration from the TXSeries Administration Console or cicscp.
   2. Grant privileges on Oracle views

      Grant the select privilege on the dba_pending_transactions view to all users who are specified in the XA open string. For example, if you need to connect to your database only as user scott, run the following sqlplus command:

      grant select on dba_pending_transactions to scott;

2. Build the switch load file (if an XA transaction environment is used)

   Makefiles to build the two types of switch load file are supplied with CICS. Several makefiles exist:

   oracle1pc.mk

   Single-phase commit

   oraclexa_dyn.mk

   Two-phase commit with dynamic registration

   oraclexa_sta.mk

   Two-phase commit without dynamic registration

   Build the switch load file as follows:

   1. Ensure that your working directory is your region's bin directory.
   2. Ensure that the ORACLE_HOME environment variable is set to the Oracle home directory.
   3. Copy the switchload file, makefile and source files to the region's bin directory.
   4. Use the nmake command to build the makefile. For example:

      nmake -f makefile

      where makefile is one of the makefiles that are listed at the start of step 2.
3. Prepare the region
   1. Set up the region's environment

      The region's environment is inherited from the system environment. You can add database environment information to the region's environment file (c:\var\cics_regions\regionName\environment) to avoid connection errors that occur if the system environment does not have the required database environment variables set.

      If the Oracle SQL libraries are not included in the system environment, they must be included in the region's environment file. When adding the library path to the region's environment file, ensure that all the libraries that are required by applications that run on this region are included. This is because the library path value that existed when the region was started is replaced with the library path value that is in the region's environment file. This is true for all values, such as PATH, NLSPATH, LANG, and so on.

      Do not use % values in the region's environment file because these values are not expanded. Refer to the information that is in the region's environment file prolog.

   2. Add the Product Definition to the region.

      Use the CICS Product Definition to define an XA-compliant Resource Manager to CICS.

      The following attributes in each stanza are of particular importance:

      • Resource manager initialization string (XAOpen): This attribute defines the XA open string. The string includes the following:

        Oracle_XA +Acc=P/userName/password
                       +SesTm=sessionTimeLimit

        The user name and password can be null if "P//" is a valid user name-password pair.

        Refer to your Oracle documentation for a detailed description of all fields that can be used in the XA open string.

        An example of an XA open string for Oracle follows:

            Oracle_XA+Acc=P/scott/tiger+SesTm=35+LogDir=C:\TEMP+DbgFl=1

        This string causes a cicsas process to connect to the database:
        • As user scott with password tiger (Acc=P/scott/tiger)
        • With inactive transactions aborted after 35 seconds (SesTm=35)
        • With log files created in the C:\TEMP directory (LogDir=C:\TEMP)
        • With XA procedure calls and returns logged in the log file (DbgFl=1)
        Passwords passed to the resource manager in the XA_Open string can be stored in either clear text or secure form. To use the secure XA password feature, enter the annotated password @password@ where you want the password to go. Example for secure XA password is as shown:

        Oracle_XA+Acc=P/scott/@password@+ SesTm=35+LogDir=/tmp+DbgFl=1

        Run the cicsxapasswd command by passing the region name and the Product Definitions (XAD) key. For more information, see cicsxapasswd - Configures the XA password.

      • Switch load file: This attribute is a string that defines the name of the switch load file object. Instructions that explain how to build an appropriate switch load file are given in step 2.

        If your switch load file is called oraclexa_dyn.dll and it is in the region/bin directory, set the switch load file attribute to oraclexa_dyn.dll.

      • Resource manager termination string (XAClose): This attribute defines the resource manager close string. Set it to a null string ("").
4. Build the Micro Focus COBOL/COBOL-IT runtime (if COBOL is to be used).

   On Windows systems, no action is required to provide a language environment for CICS. The COBOL language method file cicsprCMFNT and the COBOL-IT language method file, cicsprCOBOLIT are provided in the $cics_install_dir\bin directory.

   Before compiling an COBOL-IT ORACLE program, edit the default.conf file provided in $COBOLITDIR/config directory and add the include "oracle.symb" string. This will ensure that all the ORACLE symbols are linked at link time itself.

5. Verify the connection

   CICS logs XA messages in the region's console file. To determine whether the region can connect to RM, start your region and check the console.nnnnnn messages.

   1. Cold start the region.
   2. Check the console messages when they are logged to the console. The first XA messages are generated when the CICS application servers are started. If XA problems occur, check for additional information in the Oracle trace file. (See 3.b).
6. Test the connection

   The CICS-supplied examples provide an easy way of exercising XA and non-XA connections. These examples are in c:\opt\cics\examples\xa and c:\opt\cics\examples\nonxa. Refer to the respective README files.