Overview

Oracle Tuxedo is now available on the OpenVMS platform. This book is designed for experienced Oracle Tuxedo developers who are porting applications to OpenVMS.

The topics covered in this chapter include:

•	Getting Started

•	Configuring Oracle Tuxedo on OpenVMS

•	Developing Oracle Tuxedo Applications for OpenVMS

•	Networking on OpenVMS

Getting Started

The following sections answer general questions about the unique Oracle Tuxedo characteristics on the OpenVMS platform:

•	What hardware and software are required?

•	Can I run Oracle Tuxedo for OpenVMS with other Oracle Tuxedo releases?

•	How are files specified?

•	What file naming conventions are used?

Interoperability

Oracle Tuxedo for OpenVMS servers and clients can interoperate with any Oracle Tuxedo release.

File System Specification

A file specification on the OpenVMS operating system consists of up to seven components, several of which assume a default value if they are not specified. A complete OpenVMS file specification takes the following form.

Node$device:[root.][directory-name]filename.type;version

Table 1‑1 defines each component of an OpenVMS file specification.

 

Table 1‑1 OpenVMS Components

Component	Definition
node	Optional cluster name (containing no more than 59 characters), followed a dollar sign ($).
device	Optional device specification (containing no more than 15 characters), followed by a colon (:).
[root]	Optional root directory name (containing no more than 39 characters) within square brackets and followed by a period (.)
[directory-name]	The path name for the directory in which the file (specified by filename) resides. The path name must be specified within square brackets. Directory names within the path name are separated by periods. The path name may be no more than eight levels deep. Each directory name may be no more than 39 characters. Optional component.
filename	File name (containing no more than 39 characters), followed by a period.
type	Type of the file (containing no more than 39 characters), followed by a semi-colon (;).
version	Version number (containing no more than 5 digits) of the file. The largest version number is the most recent copy of a file.

Note:

The entire name cannot be longer than 256 characters. All file names are case insensitive. Thus, for example, the names UBBCONFIG.DAT and ubbconfig.dat refer to the same file.

The following is an example of a file specification.

MYCLUSTER$DKA100:[Tuxedo.APPS.SIMPAPP]UBBCONFIG.DAT;2

File specifications end with a semi-colon (;) and have a version number. Older versions of a file can be removed with the PURGE command.

All Oracle Tuxedo files that contain file names (such as TUXCONFIG) must use the native OpenVMS format. File specifications can be separated by a comma (,). For example, APPDIR might be specified as

APPDIR="DKA100:[Tuxedo.APPS.SIMPAPP],DKA100:[Tuxedo.APPS.QSAMP]"

File Naming Conventions

OpenVMS has several naming conventions. Table 1‑2 lists valid file extensions and how they are interpreted by OpenVMS and Oracle Tuxedo.

 

Table 1‑2 Valid File Extensions

Use This Extension	For This Type of File
.C	C source file
.COB	COBOL source file
.COM	Script containing DCL commands that will be run by the command interpreter
.CPY	COBOL copy file
.EXE	Binary executable file or shared library (executable image)
.H	C header file
.OLB	Binary static object library
.OPT	File in which you can specify options (such as functions to be exported from a library) that will be used by the linker
.VV	Binary view file compiled with viewc(1) or viewc32(1)

Note:

The .EXE extension is not required for server names listed in the UBBCONFIG file. If the extension is required to make a server executable, Oracle Tuxedo adds it to the server name at runtime.

Configuring Oracle Tuxedo on OpenVMS

The following sections explain the unique characteristics of configuring Oracle Tuxedo on the OpenVMS platform.

Logical Names

All environment variables needed by Oracle Tuxedo applications should be defined as logical names. For example, the TUXCONFIG, FLDTBLDIR32, FIELDTBLS32, VIEWDIR32, and VIEWFILES32 variables need to be defined as logical names. These names should be specified in the native OpenVMS format and must be defined in the process table of the process running the Oracle Tuxedo commands. Most of the processes spawned by Oracle Tuxedo utilities inherit logical names from the current process table.

If you are using the Oracle Tuxedo Workstation feature, the WSNADDR and WSTYPE variables must be defined as logical names. All UNIX system environment variables are logical names in OpenVMS.

For example, you can set the TUXCONFIG environment variable with the following DCL command:

$ DEFINE TUXCONFIG DKA100:[Tuxedo.APPS.SIMPAPP]TUXCONFIG.

We recommend setting these logical names in the process table of the process running the Oracle Tuxedo commands. Usually you place logical names, such as those of the Oracle Tuxedo shared libraries, in the group or system tables. These logical names are relevant to a specific installation of the Oracle Tuxedo binaries. You should set logical names that are specific to a particular Oracle Tuxedo application in the process table. If desired, you can specify application-specific logical names in any logical table that a detached process will be able to access.

When assigning a value to an environment variable, you may specify more than one directory. Provide the path name of each directory and use a comma (,) to separate path names. For example, in the following line, two directories (SIMPAPP and BANKAPP) are assigned to the APPDIR variable.

$ DEFINE APPDIR DKA100:[Tuxedo.SIMPAPP],DKA100:[Tuxedo:BANKAPP]

If the SHOW LOGICAL command is run on APPDIR, the output looks similar to the following:

$ SHOW LOGICAL APPDIR
"APPDIR" = "DKA100:[Tuxedo.SIMPAPP]" (LNM$PROCESS_TABLE)
= "DKA100:[TUXEDO.BANKAPP]"

Oracle Tuxedo can interpret logical names that include multiple values. Path-related directives in the UBBCONFIG file should be formatted in UPPER CASE.

DCL PATH

The DCL$PATH should include the path names for the Oracle Tuxedo installation directory and Tuxedo application servers, as shown in the following example:

"DCL$PATH" = "DKA100:[WSCOTT.BIN]" (LNM$PROCESS_TABLE)
= "DKA100:[Tuxedo.BIN]"
= "SYS$SYSTEM:"

Command-line Programs

All upper-case arguments to Oracle Tuxedo commands (such as tmboot and tmshutdown) must be enclosed in double quotes on the command line. If they are not, they will be converted to lower case by OpenVMS and misinterpreted by the system.

$ tmboot "-A"

Any command that might run a shell script is run through the DCL interpreter, and hence should be a proper DCL script. An example of a Oracle Tuxedo service that might run scripts is the qmadmin threshold command.

Hostname Utility

You must enter the name by which your machine is known to the network (your network node name) in the MACHINES section of the UBBCONFIG file. Use the hostname utility to determine your machine node name. An example of the output of the hostname utility is:

lcvms1.us.oracle.com

You must enclose a network node name in quotes when you enter it in the MACHINES section of the UBBCONFIG file. (Quotes are not required if a network node name does not contain any periods.)

ID Utility

The id utility displays the UID (user ID) and GID (group ID) of a user account. An example of the output of the id utility is:

UID=250456, GID=234

Use the id utility to determine the values of UID and GID that you must enter in the UBBCONFIG file.

Resource Manager Information

This section describes four types of information about resource management that are used by an Oracle Tuxedo application:

•	Resource manager (RM) files

•	User log file

•	OPENINFO strings

•	DMTYPE files

RM Files

When an Oracle Tuxedo application needs to identify or locate resources (such as SQL statements, databases, and libraries), the application refers to a resource manager file, or RM file. At build time, when you use the buildclient(1) or buildserver(1) command with the -R option, the command parses the RM file and puts the library names in a temporary option file. This temporary file is appended to the list of option files read by the linker. When the build is complete, the temporary file is removed.

The RM file for OpenVMS platforms is located in the UDATAOBJ directory (created when you installed Oracle Tuxedo).

Each entry in an RM file consists of a list of resources, such as library names. Fields within an entry are separated by commas; items within a field, by blank spaces, as shown in the following sample RM entry (used for the Oracle Tuxedo SQL resource manager):

Tuxedo/SQL,tuxsql_switch,TUX_LIBSQL/SHARE TUX_LIBRMS/SHARE TUX_LIBFS/SHARE

User Log File

The Oracle Tuxedo userlog file is written through the OpenVMS Record Management Services (RMS). Because RMS performs record locking, the userlog file may not be available immediately for viewing. Oracle Tuxedo warning, error, and informational messages can be found in the userlog file as defined by the appropriate ULOGPFX variable.

OPENINFO Strings

A Oracle Tuxedo application opens a database for transactions by invoking the tpopen(3c) function. tpopen(), in turn, looks up the setting of the OPENINFO string (in the application code) to find out the name and location of the database to be opened.

Fields within the value of the OPENINFO string are separated by commas, as shown in the following example (from the OPENINFO string in the bankapp sample application):

OPENINFO="Tuxedo/SQL,DKA100:[OracleDEV.APPS.BANKAPP]BANKDL1,BANKDB,readwrite"

DMTYPE Files

An Oracle Tuxedo application builds a Domains gateway process by invoking the build_dgw(1) command. This command requires, as an argument, a file called DMTYPE, which contains a list of the libraries to be linked to the new gateway.

Each entry in the DMTYPE file contains the name of one or more libraries. Library names are separated by commas. For example, the following line is an entry in the DMTYPE file for GWTDOMAIN (a standard server for Oracle Tuxedo Domains):

TDOMAIN,TUX_LIBGW/SHARE TUX_LIBNWS/SHARE,,

Developing Oracle Tuxedo Applications for OpenVMS

The following sections explain the unique characteristics of developing Oracle Tuxedo applications on the OpenVMS platform.

Building Clients and Servers

The buildclient(1) and buildserver(1) utilities are fully supported on the OpenVMS platform. We recommend using these utilities to ensure that the proper options and libraries are used.

When building clients and servers, you must specify which prototypes of the Oracle Tuxedo API are to be used.

 

Table 1‑3  

If you are using this compiler . . .	Then specify this qualifier . . .
CC	/prefix=all /names=as_is /float=ieee
COBOL	/ansi_format

The buildclient(1) and buildserver(1) utilities automatically use these qualifiers for any files they compile.

Note:

Since only 64-bit binary generating on OpenVMS platform is currently supported, buildclient(1) and buildserver(1) default to add option like "/po=lo=argv" to compiler. You should follow this rule to create your own obj files as well as to link with Oracle Tuxedo.

When linking Oracle Tuxedo clients and servers, you must include the linker option file, TUXLIB.OPT (in the LIB directory of the Oracle Tuxedo installation) in the link line. Both the buildclient(1) and buildserver(1) utilities automatically append the TUXLIB.OPT file to the link line. Remember that option files must be qualified for the linker with the /OPT switch. For an example of how to use an option file in a Oracle Tuxedo link line, see the compile and link line in Example 2.

As on the UNIX platform, the CFLAGS logical name allows you to add options to the compile phase of the build. The LINK phase of the OpenVMS build may need different options. You can supply options to the LINK phase of the build with the logical name TMLKFLAGS.

buildclient(1) and buildserver(1) sometimes produce warnings about the Oracle Tuxedo libraries. These warnings should be ignored. The Oracle Tuxedo libraries have circular references, and when they are built warnings are produced.

By using Oracle Tuxedo shared libraries, Oracle Tuxedo users on OpenVMS can take advantage of the Oracle Tuxedo buffer type switch functionality. See buffer(3c) in the Oracle Tuxedo Reference Manual.

Example 1

The following example shows how you can run buildclient(1) to create a client called SIMPCL.EXE.

$ BUILDCLIENT -f SIMPCL.C -o SIMPCL.EXE
%LINK-W-SHRWRNERS, compilation warnings
in shareable image file DKA100:[Tuxedo.LIB]LIBTUX_1030.EXE;1
%LINK-W-SHRWRNERS, compilation warnings
in shareable image file DKA100:[Tuxedo.LIB]LIBBUFT_1030.EXE;1

In this example, the linker returns two warning messages about Oracle Tuxedo libraries. These messages are not significant; you may ignore them.

Example 2

Option files provide a useful way to specify a large number of files on the link line. In the following example, an option file is used to specify a set of object files (ECHO.OBJ, PROCESS.OBJ, and SECD.OBJ) that have been compiled and will be linked into our server.

$ TYPE SECD.OPT
!
! OPTION FILES USE ! in order to denote comment lines
! Any line which starts with ! is ignored by the linker
!
ECHO.OBJ
PROCESS.OBJ
SECD.OBJ
TUX_LIBTMIB /SHARE
$ BUILDSERVER -f SECD.OPT/OPT -o SECD.EXE -s "SECD:ECHO" -s "PROFILE"

Notice the following components of the file:

•	TUX_LIBTMIB is a logical name that should point to the Oracle Tuxedo LIBTMIB_1030.EXE shared library in the LIB directory of your Oracle Tuxedo installation.

•	If your server or client needs to access the MIB through tpadmcall(3c), then the TUX_LIBTMIB library should be linked into your client or server.

•	The /SHARE qualifier tells the linker that this file is a shared library. (Another option available for the type qualifier is /LIB, which tells the linker to expect a non-shared library file.)

•	Double quotes are used to preserve the upper-case spelling of the parameters specified with the -s option ("ECHO" and "PROFILE").

Tips for Calling External Code and Input into your Application

This section provides tips for writing the code in your application for:

•	Running executables

•	Running DCL scripts

•	Redirecting standard I/O and standard error streams

Running Executables

In order to have your application invoke an executable, you must do one of the following:

•	Include in your code the definition of a symbolic name for the executable

•	Specify the location of the executable through the DCL$PATH variable

To define a symbolic name, enter the name and specify the path for the target executable. The executable must be a DCL script.

For example, to define a symbol for the simpapp client simpcl, enter the following line in your application:

$ SIMPCL :== $ DKA100:[Tuxedo.SIMPAPP]SIMPCL.EXE

This line defines simpcl as a symbolic name. The SIMPCL.EXE executable can now be run with arguments:

$ SIMPCL "Here is a string"
HERE IS A STRING

If the DCL$PATH variable includes the directory in which the SIMCL.EXE executable is located, you do not need to define a symbolic name for the executable.

Running DCL Scripts

To run a DCL script from the command line, enter the @ symbol before the name of the script.

Redirecting the Standard I/O and Error Streams

If your code invokes programs that take input from standard input (such as qmadmin or tmadmin), then you will probably want to redirect standard input. Oracle Tuxedo allows you to do so.

To redirect standard input, standard output, and standard error on an OpenVMS platform, redefine the logical names SYS$STDIN, SYS$STDOUT, and SYS$STDERR.

The following example shows how a qmadmin script generates queue spaces and redirects its output to two files: qmadmin.stdout and qmadmin.stderr.

$ TYPE QMADMIN.STDIN
echo
crdl DKA100:[Tuxedo.QSAMPLE]QUE 0 400
qspacecreate
QSPACE
62839
100
6
4
9
3
errque
y
16
q
$ define sys$input "DKA100:[Tuxedo.QSAMPLE]QMADMIN.STDIN"
$ define sys$output "DKA100:[Tuxedo.QSAMPLE]QMADMIN.STDOUT"
$ define sys$error "DKA100:[Tuxedo.QSAMPLE]QMADMIN.STDERR"
$ qmadmin
$ deassign sys$input
$ deassign sys$output
$ deassign sys$error
$ TYPE CRQUE.STDERR
qmadmin - Copyright (c) 1996 Oracle Systems, Inc.
Portions * Copyright 1986-1997 RSA Data Security, Inc.
All Rights Reserved.
Distributed under license by Oracle Systems, Inc.
TUXEDO is a registered trademark.
$ TYPE CRQUE.STDOUT
%DCL-I-SUPERSEDE, previous value of SYS$ERROR has been superseded
QMCONFIG=DKA100:[Tuxedo.QSAMPLE]QUE
> Echo is now on
> crdl DKA100:[Tuxedo.QSAMPLE]QUE 0 400
Created device DKA100:[Tuxedo.QSAMPLE]QUE, offset 0, size 400 on DKA100:[TUXEDO.QSAMPLE]QUE
> qspacecreate
Queue space name: IPC Key for queue space: Size of queue space in disk pages: Number of queues in queue space: Number of concurrent transactions in queue space: Number of concurrent processes in queue space: Number of messages in queue space: Error queue name: Initialize extents (y, n [default=n]): Blocking factor [default=16]:

> q

Networking on OpenVMS

When run on other platforms, Oracle Tuxedo utilities require a bridge or a device to be specified on the command line. When you run the same utilities on the OpenVMS platform, however, you should not specify a bridge or a device. If you do so, a warning message will be printed in the userlog file.