Skip Headers

Oracle8i Server Installation and Database Administration Guide
Release 3 (8.1.7) for Fujitsu Siemens Computers BS2000/OSD

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

Go to previous page Go to next page

UTM Product Set

This chapter describes how to use the Oracle Server for BS2000/OSD UTM product on Fujitsu Siemens machines running the BS2000/OSD operating system and Oracle Server release 8.1.7. The following areas are covered:

Refer to the Oracle8i Application Developer's Guide (ch. Oracle XA) for a general description of concepts.

Differences from the generic concepts:

Operation of Oracle Server Databases Using UTM Programs

The Universal Transaction Monitor (UTM) controls the execution of user programs that can be used from a large number of terminals at the same time.

A UTM application consists of a structured sequence of processing stages that are supplied with access rights for the specific user. These stages, in turn, consist of UTM transactions that are carried out either in their entirety, or not at all.

If several users are working under UTM at the same time then simultaneous access to the shared database is also usually required. The database/data communications system (DB/DC system), Oracle Server-UTM, synchronizes access by UTM applications to Oracle Server databases, and ensures that the database remains in a consistent state. In the event of system failure, the DB/DC system performs an automatic recovery which ensures that the database remains in a consistent state.

Synchronisation of Oracle and openUTM takes place through Oracle´s XA library.

Distributed UTM Files

When you install the Oracle Server, as described in the chapter "Installing/Upgrading Oracle Server Software" the UTM part of the Oracle Server is installed. The distributed UTM files comprise:


Perform the following steps to install (after studying the XA-chapter in Oracle8i Application Developer's Guide):

  1. Run INSTALL.P.UTM, if you have not already run INSTALL.P.ORACLE

  2. Grant the SELECT privilege, e.g.

    grant select on DBA_PENDING_TRANSACTIONS to scott;

    to the DBA_PENDING_TRANSACTIONS table for all UTM users connecting to the Oracle Server database. The UTM users are identified by the message "user access information". See Defining an Open String below in this chapter.

Developing an Oracle Server/UTM Application

The steps involved in developing an Oracle Server application under UTM are described in this section. The main steps are as follows:

In addition, this section also describes how you define open strings and how you use precompilers with the Oracle XA library.

  1. Building the UTM program units:
    (see the UTM manual Programming Applications and the
    Oracle8i for Fujitsu Siemens BS2000/OSD User's Guide)

  2. Defining the configuration:
    (see the UTM manual Generating and Administering Applications )

    An Oracle Server/UTM application requires the following information for execution:

    • information about the application

    • username/password with access protection

    • information about the terminal and communication partners

    • information about the transaction codes

    These properties collectively form the configuration, which is stored in the KDCFILE. The configuration definition is carried out by the KDCDEF utility.

    This section gives the descriptions for three commands important for connection to the Oracle Server. These are as follows:


      When the Oracle Server/UTM application is generated, you must specify that UTM communicates with the Oracle Server. Enter the following:


    When running the Oracle Server under UTM with multi-database support (that is running two different database systems in parallel), the non-Oracle Server database must be the first database specified and the Oracle Server database the second.


    The UTM parameter LIB does not necessarily have to be specified, since the necessary information is also in the ORAENV file. However, if you do decide to use the LIB operand, then specify the library UTM.ORAUTM.LIB.

    • OPTION

      If you specify the corresponding GEN operand in the OPTION command, then the KDCDEF utility also produces the source-code for the KDCROOT table module. The syntax of OPTION is as follows:

    • MAX

      Another important operand is APPLIMODE, which is specified in the MAX command. This determines re-start behavior after a system failure. The syntax of MAX is as follows:


      APPLIMODE=SECURE means that UTM continues after an application crash with a co-ordinated warm-start of the UTM application and the Oracle Server.

      If you specify APPLIMODE=FAST, no UTM application re-start is carried out, as UTM stores no re-start information. In the event of an error, the application starts from scratch. Transactions that are still open after a UTM-application crash are rolled back automatically.

    See the UTM.DEMO.P.KDCDEF file for an example procedure for building the KDCFILE and the KDCROOT table module.

  3. Translating the KDCROOT table module and UTM program units:

    The KDCROOT table module should be compiled, and the UTM program units should be translated to the corresponding compilers. See the example procedure UTM.DEMO.P.KDCROOT for translation of the KDCROOT table module.

  4. Linking the UTM application program:

    The UTM application program is produced by linking the KDCROOT table module with the UTM program units.

    Instead of writing your own binding procedure you should use the example procedures UTM.DEMO.P.PROBIND (for linking with TSOSLNK) or UTM.DEMO.P.PROBIND.LLM (for linking with binder)
    and apply modifications when needed.

    If you cannot do without writing your own binding procedure please study the examples carefully before.

  5. Starting the UTM application:

    An example procedure for starting the UTM application can be found in the file UTM.DEMO.P.PROSTRT.

    When loading the UTM application, you must specify the initialization parameters for UTM, as well as for the Oracle Server.

    The UTM initialization parameters are described in the UTM manual "Generating and Handling Applications".

    The Oracle Server initialization parameters are specified in a similar way to the UTM initialization parameters:

    	.ORACLE open string

Defining an Open String

This section describes how to construct an open string. This string is used by the transaction monitor to open the database. The maximum number of characters in an open string is 256, and the maximum number of open strings is 8. Construct the string as follows:


where the required_fields are:

and where the optional_fields are:


  • You can enter the required fields and optional fields in any order when constructing the open string.

  • All field names are case-insensitive, although their values may or may not be case-sensitive depending on the system.

  • You may not use the "+" character as part of the actual open string.

Required Fields

The required fields for the open string are:

Item Meaning


Specifies user access information.


Indicates that explicit user and password information is provided.


A valid Oracle Server username.


The corresponding current password.

For example, Acc=P/scott/tiger indicates that user and password information is provided. In this case, the user is scott and the password is tiger.

For the correct process, make sure that scott has the SELECT privilege on the DBA_PENDING_TRANSACTIONS table.

Item Meaning


Specifies the maximum amount of time a transaction can be inactive before it is automatically deleted by the system.


This value should correspond to what you require as a maximum time from initiation of a global transaction and the completed commit or rollback of that transaction.


The unit for this time limit is seconds. A value of 0 indicates no limit. For this release, the value must always be set to 0 (unlimited), as a termination due to a session time limit will not be handled correctly and may cause abnormal termination.

Optional Fields

Optional fields for the open string are described below.

Item Meaning


Specifies the database name.


Indicates the name used in Oracle Server precompilers to identify the database.

Application programs that use only the default database for the Oracle Server precompiler (that is, do not use the AT clause in their SQL statements), should omit the DB=db_name clause in the open string.

Note: This default database is represented in the ORAENV file by ORASID.

Applications that use explicitly-named databases should indicate that database name in theirDB=db_name field.

For example, DB=payroll indicates that the database name is payroll and that the application server program will use that name in AT clauses.

For more information about precompilers (specifically Pro*C), refer to the section"Using Precompilers with openUTM" later in this chapter.

Item Meaning


Specifies the number of cursors to be allocated when the database is opened. It serves the same purpose as the precompiler option maxopencursors.


Indicates the number of open cursors. The default is 10.

For example, MaxCur=5 indicates that the process should try to keep five open cursors cached.

For more information on maxopencursors, refer to the Programmer's Guide to the Oracle Precompilers.

Item Meaning


Specifies the SQL*Net connection string.


Indicates the string to be used to log onto the system. This can be any supported Net8 connect string.

For example:

SqlNet=MADRID_FINANCE indicates an entry in TNSNAMES.ORA referencing a protocol, a host and a portnumber (for more information, see Chapter 9, "Net8").

Item Meaning


Specifies if debugging should be enabled (debug flag). For more information see Debugging below in this chapter.


This section contains examples of information strings using the above information.


If the string is longer than one line, refer to the UTM documentation for information about how to split up the string information.





Using Precompilers with openUTM

You can choose from two options when interfacing with precompilers:

Note that you should run all precompiler programs with the option release_cursor set to no. Precompiler programs may be written in C or COBOL. In the following examples, the precompiler Pro*C is used.

Using Pro*C with the Default Database

To interface to Pro*C with the default database, ensure that the DB=db_name field, used in the open string, is not present. The absence of this field indicates the default connection as defined in the ORAENV file, and only one default connection is allowed per process.

The following is an example of an open string identifying a default Pro*C connection:


Note that DB=db_name is absent, indicating an empty database identifier string.

The syntax of a select statement would be:


Using Pro*C with a Named Database

To interface to Pro*C with a named database, include the DB=db_name field in the open string. Any database you refer to must reference the same db_name specified in the corresponding open string.

An application may include the default database, as well as one or more named databases, as shown in the following examples.

For example, suppose you want to update an employee's salary in one database, the department number (deptno) in another, and the manager information in a third database. You would configure the following open strings in the transaction manager:


Note that there is no DB=db_name field in the first open string.

In the application server program, you would enter declarations such as:


Again, the default connection (corresponding to the first open string that does not contain the db_name field) does not require a declaration.

When doing the update, you would enter statements similar to the following:

EXEC SQL AT PAYROLL update emp set sal=4500 where empno=7788;
EXEC SQL AT MANAGERS update emp set mgr=7566 where empno=7788;
EXEC SQL update emp set deptno=30 where empno=7788;

There is no AT clause in the last statement because it refers to the default database.

You can use a character-host variable in the AT clause, as the following example shows:

db_name1 CHARACTER(10);
db_name2 CHARACTER(10)
set db_name1 = 'PAYROLL'
set db_name2 = 'MANAGERS'
EXEC SQL AT :db_name1 UPDATE...
EXEC SQL AT :db_name2 UPDATE...

For more information, refer to the section in the Programmer's Guide to the Oracle Precompilers that discusses concurrent logons.


  • Application servers must not create Oracle Server database connections of their own. Therefore, a UTM user is not allowed to issue CONNECT statements within a UTM program. Any work performed by them would be outside the global transaction, and may confuse the connection information given by UTM.

  • SQL calls must not occur in the UTM start exit routine, however may occur in the conversation exit routine (,,Vorgangs-Exit")


This section discusses how you recover data if there are problems or a system failure. Both trace files and the recovery of any pending transactions are discussed.

Trace Files

The Oracle XA library logs any error and tracing information to its trace file. This information is useful in supplementing the XA error codes. For example, it can indicate whether an open failure is caused by an incorrect open string, failure to find the Oracle Server instance, or a login authorization failure. The name of the trace file is:


is the process identifier (TSN)

is the database name you specified in the open string field DB=db_name

is the date when the trace file is created

Trace File Examples

Examples of two types of trace files are discussed below.

The following example shows a trace file for an application's task '1234' that was opened on April 2nd 1999. Its DB field was not specified in the open string when the resource manager was opened.


The following example shows a trace file that was created on December 15th 1998 by task '5678'. Its DB field was specified as FINANCE in the open string when the resource manager was opened.


Note that multiple Oracle XA library resource managers (that is, instances) with the same DB field in their open strings, log all trace information that occurs on the same day to the same trace file.

Each entry in the trace file contains information that looks like this:

1032.2: xa_switch rtn ORA-22

where 1032 is the time when the information is logged, 2 is the resource manager identifier, xa_switch is the module name, and ORA-22 is the returned Oracle Server information.


You can specify the DbgFl (debug flag) in the open string. For more information see Oracle8i Application Developer's Guide, ch. Oracle XA.

Depending on the debugging level (low: DbgFl=1, high: DbgFl=15) you can get more or less debug entries in the trace file (see above).

In-Doubt or Pending Transactions

In-doubt or pending transactions are transactions that have been prepared but not yet committed to the database.

Generally, UTM resolves any failure and recovery of any in-doubt or pending transaction. However, the Database Administrator may have to override an in-doubt transaction in working with UTM-F (that is, APPLIMODE=FAST), for example when the in-doubt transaction is:

Oracle Server SYS Account Tables

There are four tables under the Oracle Server SYS account that contain transactions generated by regular Oracle Server applications and Oracle Server/UTM applications. These are as follows:

For transactions generated by Oracle Server/UTM applications, the following column information applies specifically to the DBA_2PC_NEIGHBORS table:

Remember that the db_name is always specified as DB=db_name in the open string. If you do not specify this field in the open string, then the value of this column is for transactions that are generated by Oracle Server/UTM applications.

For example, you could use the following sample SQL statement to find out more information about in-doubt transactions that are generated by Oracle Server/UTM applications.

n.DBID = 'xa_orcl';

Warm-Start Problem Under UTM-D

If a UTM-D application terminates with the message "Term-Application 'ENDPET'", then it is possible that the rows have been locked after a warm-start. This can happen when an application is in the PTC (Prepare To Commit) at the point when a crash occurs, and the connection to a related UTM-D application is no longer available.

If this situation is not resolved within a few minutes, you should terminate the UTM-D application manually using KDCSHUT W, and start up again so that open transactions are reset. Do not adjust the tables DBA_2PC_PENDING and DBA_2PC_NEIGHBORS manually, since inconsistencies can occur between Oracle Server and UTM.


You can avoid this problem by setting the appropriate PTCTIME operand in the KDCDEF command UTMD.

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

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