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:
The following sections answer general questions about the unique Oracle Tuxedo characteristics on the OpenVMS platform:
Oracle Tuxedo for OpenVMS servers and clients can interoperate with any Oracle Tuxedo release.
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.
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]"
OpenVMS has several naming conventions. Table 1-2 lists valid file extensions and how they are interpreted by OpenVMS and Oracle Tuxedo.
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. |
The following sections explain the unique characteristics of configuring Oracle Tuxedo on the OpenVMS platform.
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.
The DCL$PATH
should include the path names for the Oracle Tuxedo installation directory, as shown in the following example:
"DCL$PATH" = "DKA100:[WSCOTT.BIN]" (LNM$PROCESS_TABLE)
= "DKA100:[Tuxedo.BIN]"
= "SYS$SYSTEM:"
All upper-case arguments to Oracle Tuxedo commands (such as tmboot
and tmshutdow
n) 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.
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.)
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.
This section describes four types of information about resource management that are used by an Oracle Tuxedo application:
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
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.
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"
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,,
The following sections explain the unique characteristics of developing Oracle Tuxedo applications on the OpenVMS platform.
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.
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.
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.
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.tpadmcall(3c)
, then the TUX_LIBTMIB
library should be linked into your client or server./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.)ECHO
" and "PROFILE"
).This section provides tips for writing the code in your application for:
In order to have your application invoke an executable, you must do one of the following:
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.
To run a DCL script from the command line, enter the @
symbol before the name of the script.
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
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.