C H A P T E R 13 - Configuring a Region to Work With an RDBMS

C H A P T E R 13

Configuring a Region to Work With an RDBMS

This chapter describes how to configure a region to work with relational database management systems (RDBMS). The following sections describe each of the tasks:

Setting RDBMS Environment Variables

Selecting an RDBMS Using kixinstall

Specifying RDBMS Values in the SIT

After completing the configuration, you can customize the user exit routine for your database, if required. Refer to the Sun Mainframe Transaction Processing Software Administrator's Guide for information.

Note - If you are also using Sun MBM with an RDBMS, refer to the Sun Mainframe Batch Manager Software Configuration Guide.

Setting RDBMS Environment Variables

Each database has its own set of environment variables that must be set before you can configure the region and use the database. See Chapter 2 for the procedures to set environment variables. Also refer to the RDBMS documentation.

The following table shows each database and its environment variables.

TABLE 13-1 Database Environment Variables
Database	Environment Variables
DB2	`DB2DBDFT, DB2INSTANCE, INSTHOME`
Oracle	`ORACLE_HOME, ORACLE_SID, TWO_TASK`
Sybase	`SYBASE`

For more information about the environment variables, refer to the README.doc file in the database directory for your database in $UNIKIX/test. For example, the COBOL Oracle file is $UNIKIX/test/oracle/cobol/README.doc. The README.doc file also contains instructions on running the sample account application with your database.

Selecting an RDBMS Using `kixinstall`

After you set the environment variables for your database, follow these steps to select your database and build the Sun MTP executables using the Configuration Utility.

To Select an RDBMS

1. Change to the $UNIKIX/src directory.

2. Run the kixinstall utility.

3. Select option 2 on the Configuration Utility main menu and press Return.

4. When the RDBMS Configuration screen is displayed (FIGURE 13-1), type the number of the RDBMS you are using.

You can select more than one RDBMS.

Press R to deselect an RDBMS.

FIGURE 13-1 RDBMS Configuration Screen

Screen shot of the RDBMS selection screen of the Configuration Utility.

[ D ]

Note - If the environment variables for the RDBMS are not set, an error is displayed indicating that you must set them before you can continue.

5. Press Return to display the Configuration Utility main menu.

6. Finish the configuration process as described in the Sun Mainframe Transaction Processing Software Installation Guide.

Specifying RDBMS Values in the SIT

Sun MTP provides a facility in the user exit modules that looks up the database-specific information in the SIT during region initialization. If you do not want to use this default method, you must customize the user exits and you can skip this section.

To Set RDBMS-Specific Values in the SIT

1. Open the Table Manager and display the Standard Tables menu.

2. Press PF1 to open the SIT.

FIGURE 13-2 System Initialization Table (SIT)

[ D ]

3. If you have not customized the SIT for your environment, follow the steps in Customizing the SIT.

4. Type values in the appropriate RDBMS fields using the information in TABLE 13-2.

The following four fields are returned in the user exit program for the RDBMS. The user exit programs can be called during initialization to connect to the specified database.

Server: Name of the server for connection to RDBMS user exit programs.

DbName: Relational database name for connection to the RDBMS user exit programs.

UserID: Relational database user name for connection to the RDBMS user exit programs.

PassWd: Relational database password for connection to the RDBMS user exit programs.

5. Press PF2 to save the SIT.

6. Press PF3 to exit the SIT.

The following table shows each RDBMS and the fields required in the SIT.

TABLE 13-2 RDBMS Values for SIT
Table Value/ Database	Server	UserID	DbName	PassWd
DB2	No	No	Yes	No
Oracle	Remote ^[1]	Yes	No	Yes
Sybase	Yes	Yes	No	Yes

Oracle Caveats

If you are using a remote Oracle database, you must supply a server name in the SIT. This server must be defined in the Oracle TNSNAMES.ORA file. Refer to the Oracle documentation for information about defining entries in this file.

If you are using a local Oracle database and mistakenly supply a server name in the SIT, you will receive the Oracle SQL code -12154 when trying to start the region, and the region will not start.

Starting a Region With an RDBMS

If you rebuilt the Sun MTP transaction server to connect to an RDBMS, you must specify this alternate transaction server when you start the region.

To Start the Region With an RDBMS

1. Set all the appropriate values in the SIT.

If you have already built the transaction server with RDBMS but did not update the SIT, start the region without connecting to the RDBMS so that you can update the SIT with the correct RDBMS values. See Bypassing the RDBMS at Startup.

2. Use the -t filename option to unikixmain to specify the name and location of the alternate transaction server.

$ unikixmain -t $UNIKIX/local/bin/unikixtran  . . .

Bypassing the RDBMS at Startup

If you need to start a region without connecting to the RDBMS, use the following procedure.

To Bypass the RDBMS

1. Set the KIXRDBMS_BYPASS environment variable to any value.

For example:

$ export KIXRDBMS_BYPASS=1

2. Start the region.

An informational message is written to unikimain.log indicating that this bypass is in effect.

3. Open the Table Manager and display the SIT.

4. Replace the value in the Server field with blank spaces.

5. Save the SIT.

6. Shut down the region.

7. Unset the KIXRDBMS_BYPASS environment variable.