The BEA TUXEDO system is now available on the OpenVMS platform. This book is designed for experienced BEA TUXEDO system developers who are porting applications to OpenVMS.
The topics covered in this chapter include:
The following sections answer general questions about the unique characteristics of the BEA TUXEDO system on the OpenVMS platform:
Getting Started
The following table lists the system requirements for BEA TUXEDO for OpenVMS.
Platform Requirements
BEA TUXEDO for OpenVMS servers and clients interoperate with any 6.x release of the BEA TUXEDO system. BEA TUXEDO 6.5 must be running on the master node in any multi-processor configuration.
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.
The following table defines each component of an OpenVMS file specification.
Interoperability
File System Specification
node::device:[root.][directory-name]filename.type;version
Note:
The entire name cannot be longer than 256 characters. All file names are case insensitive. Thus, for example, the names The following is an example of a file specification.
File specifications end with a semi-colon ( All BEA TUXEDO files that contain file names (such as OpenVMS has several naming conventions. The following table lists valid file extensions and how they are interpreted by OpenVMS and by the BEA TUXEDO system.
UBBCONFIG.DAT and ubbconfig.dat refer to the same file.
MYCLUSTER::DKA100:[TUXEDO.APPS.SIMPAPP]UBBCONFIG.DAT;2
;) and have a version number. Older versions of a file can be removed with the PURGE command.
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
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, the BEA TUXEDO system will add it to the server name at runtime.
The following sections explain the unique characteristics of configuring the BEA TUXEDO system on the OpenVMS platform.
All environment variables needed by BEA 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 BEA TUXEDO commands. Most of the processes spawned by BEA TUXEDO utilities inherit logical names from the current process table.
If you are using the BEA 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 BEA TUXEDO commands. Usually you place logical names, such as those of the BEA TUXEDO shared libraries, in the group or system tables. These logical names are relevant to a specific installation of the BEA TUXEDO binaries. You should set logical names that are specific to a particular BEA 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 varible, 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]"
The BEA TUXEDO system can interpret logical names that include multiple values.
The DCL$PATH should include the path names for the BEA 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 BEA 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 BEA 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 ubbconfig. Use the hostname utility to determine your machine's network node name. An example of the output of the hostname utility is:
lcvms1.beasys.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 a BEA TUXEDO application:
When a BEA 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 The RM file for OpenVMS platforms is located in the 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 BEA TUXEDO SQL resource manager):
The BEA 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. BEA TUXEDO warning, error, and informational messages can be found in the userlog file as defined by the appropriate A BEA TUXEDO application opens a database for transactions by invoking the Fields within the value of the A BEA TUXEDO application builds a Domains gateway process by invoking the Each entry in the The following sections explain the unique characteristics of developing BEA TUXEDO applications on the OpenVMS platform.
The When building clients and servers, you must specify which prototypes of the BEA TUXEDO API are to be used.
RM Files
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.
UDATAOBJ directory (which was created when you installed the BEA TUXEDO system).
TUXEDO/SQL,tuxsql_switch,TUX_LIBSQL/SHARE TUX_LIBRMS/SHARE TUX_LIBFS/SHARE
User Log File
ULOGPFX variable. No messages are written to an OpenVMS log file.
OPENINFO Strings
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.
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:[BEADEV.APPS.BANKAPP]BANKDL1,BANKDB,readwrite"
DMTYPE Files
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.
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 BEA TUXEDO Domains):
TDOMAIN,TUX_LIBGW/SHARE TUX_LIBNWS/SHARE,,
Developing BEA TUXEDO Applications for OpenVMS
Building Clients and Servers
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.
| If you are using this compiler . . . | Then specify this qualifier . . . |
|---|---|
|
CC |
|
|
COBOL |
|
The When linking BEA TUXEDO clients and servers, you must include the linker option file, As on the UNIX platform, the One characteristic of By using BEA TUXEDO shared libraries, BEA TUXEDO users on OpenVMS can take advantage of the BEA TUXEDO buffer type switch functionality. See The following example shows how you can run In this example, the linker returns two warning messages about BEA 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- Notice the following components of the file:
buildclient(1) and buildserver(1) utilities automatically use these qualifiers for any files they compile.
TUXLIB.OPT (in the LIB directory of the BEA 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 BEA TUXEDO link line, see the compile and link line in Example 2.
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) is that they always produce warnings about the BEA TUXEDO libraries. These warnings should be ignored. The BEA TUXEDO libraries have circular references, and when they are built warnings are produced.
buffer(3c) in the BEA TUXEDO Reference Manual.
Example 1
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_0000.EXE;1
%LINK-W-SHRWRNERS, compilation warnings
in shareable image file DKA100:[TUXEDO.LIB]LIBBUFT_0000.EXE;1 Example 2
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"
TUX_LIBTMIB is a logical name that should point to the BEA TUXEDO LIBTMIB_6400.EXE shared library in the LIB directory of your BEA TUXEDO installation.
This section provides tips for writing the code in your application for:
Tips for Calling External Code and Input into your Application
In order to have your application invoke an executable, you must do one of the following:
Running Executables
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 This line defines If the To run a DCL script from the command line, enter the If your code invokes programs that take input from standard input (such as To redirect standard input, standard output, and standard error on an OpenVMS platform, redefine the logical names The following example shows how a When run on other platforms, BEA 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 and the value will be ignored.
The BEA TUXEDO Web server, simpapp client simpcl, enter the following line in your application:
$ SIMPCL :== $ DKA100:[TUXEDO.SIMPAPP]SIMPCL.EXE
simpcl as a symbolic name. The SIMPCL.EXE executable can now be run with arguments:
$ SIMPCL "Here is a string"
HERE IS A STRINGDCL$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
@ symbol before the name of the script.
Redirecting the Standard I/O and Error Streams
qmadmin or tmadmin), then you will probably want to redirect standard input. The BEA TUXEDO system allows you to do so.
SYS$STDIN, SYS$STDOUT, and SYS$STDERR.
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 BEA Systems, Inc.
Portions * Copyright 1986-1997 RSA Data Security, Inc.
All Rights Reserved.
Distributed under license by BEA 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
Using a Web Server on OpenVMS
tuxwsvr, is not supported in the current release of BEA TUXEDO for OpenVMS. Instead, you should use a commercial product, such as Netscape Commerce Server for OpenVMS. Refer to "Using Netscape Commerce Server" in Chapter 3 for more information.