bldc_dce—Builds an Oracle Tuxedo ATMI client that can be called via OSF/DCE.

blds_dce [-o output_file] [-i idl_options] [-f firstfiles]
[-l lastfiles] [idl_file . . .]

bldc_dce parses any input IDL and related ACF source files and combines them with C source and object files and the OSF/DCE libraries to generate an Oracle Tuxedo ATMI client that can be called through DCE RPC (it is a DCE RPC client).

The command line arguments include the input IDL source file and options to control the actions of the IDL compiler. The options are as follows:

-o output_file

The default filename is a.out.

-i idl_options

Specifies options to be passed to the IDL compiler. Options associated with the C compilation system are automatically provided by this program. This option can be used to provide the -no_mepv option such that the application can provide a Manager Entry Point Vector.

-f firstfiles

Specifies compiler options, C source and object files to be included on the compilation before the Oracle Tuxedo ATMI system and OSF/DCE libraries.

-l lastfiles

Specifies C libraries to be included on the compilation after the Oracle Tuxedo ATMI system and OSF/DCE libraries.

blds_dce — Builds an Oracle Tuxedo ATMI server that calls OSF/DCE.

blds_dce [-o output_file] [-i idl_options] [-f firstfiles]
[-l lastfiles] [-s service] [idl_file . . .]

blds_dce parses any input IDL and related ACF source files and combines them with C source and object files and the OSF/DCE libraries to generate an Oracle Tuxedo ATMI server that can make DCE RPC calls. The primary use of this command is to make an Oracle Tuxedo system-to-OSF/DCE gateway process.

buildclient — Constructs an Oracle Tuxedo ATMI client module.

buildclient [ -C ] [ -v ] [ {-r rmname | -w } ] [ -oname]
[ -f firstfiles] [ -l lastfiles] [ -k ]

buildclient is used to construct an Oracle Tuxedo ATMI client module. The command combines the files supplied by the -f and -l options with the standard Oracle Tuxedo ATMI libraries to form a load module. The load module is built by buildclient using the default C language compilation command defined for the operating system in use. The default C language compilation command for the UNIX system is the cc(1) command described in UNIX system reference manuals.

-v

Specifies that buildclient must work in verbose mode. In particular, it writes the compilation command to its standard output.

-w

Specifies that the client is to be built using the workstation libraries. The default is to build a native client if both native mode and workstation mode libraries are available. This option cannot be used with the -r option.

-r rmname

Specifies the resource manager associated with this client. The value rmname must appear in the resource manager table located in $TUXDIR/udataobj/RM. Each line in this file is of the form:

rmname:rmstructure_name:library_names

(See buildtms(1) for further details.) Using the rmname value, the entry in $TUXDIR/udataobj/RM is used to include the associated libraries for the resource manager automatically and to set up the interface between the transaction manager and resource manager properly. Other values can be specified as they are added to the resource manager table. If the -r option is not specified, the default is that the client is not associated with a resource manager. Refer to the UBBCONFIG(5) reference page.

-o

Specifies the filename of the output load module. If not supplied, the load module is named a.out.

-f

Specifies one or more user files to be included in the compilation and link edit phases of buildclient first, before the Oracle Tuxedo ATMI libraries. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. This option may be specified multiple times. The CFLAGS and ALTCFLAGS environment variables, described below, must be used to include any compiler options and their arguments.

If -C option is specified and the environment variable COB is set to “AcuCobol”, this option only accepts COBOL source files. Other user files, such as library files, C source files, etc, must be specified with environment variable “TM_COB_CC_FILES”. See below “Environment Variable” section.

-l

Specifies one or more user files to be included in the compilation and link edit phases of buildclient last, after the Oracle Tuxedo ATMI libraries. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. This option may be specified multiple times.

-C

Specifies COBOL compilation.

-k

Keeps the COBOL client stub. buildclient generates a stub with data structures such as the function table invoked in COBOL program. This is normally compiled and then removed when the client is built. This option indicates that the source file must be kept (to see what the source filename is, use the -v option). This option is valid only when -C option is specified and the environment variable COB is set to “AcuCobol”.

Note:

The generated contents of this file may change from release to release; DO NOT count on the data structures and interfaces exposed in this file. This option is provided to aid in debugging of build problems.

TUXDIR

buildclient uses the environment variable TUXDIR to find the Oracle Tuxedo ATMI libraries and include files to use during compilation of the client process.

CC

buildclient normally uses the default C language compilation command to produce the client executable. The default C language compilation command is defined for each supported operating system platform and is defined as cc(1) for UNIX system. In order to allow for the specification of an alternate compiler, buildclient checks for the existence of an environment variable named CC. If CC does not exist in buildclient’s environment, or if it is the string "", buildclient will use the default C language compiler. If CC does exist in the environment, its value is taken to be the name of the compiler to be executed.

CFLAGS

The environment variable CFLAGS is taken to contain a set of arguments to be passed as part of the compiler command line. This is in addition to the command line option “-I${TUXDIR}/include” passed automatically by buildclient. If CFLAGS does not exist in buildclient’s environment, or if it is the string "", no compiler command line arguments are added by buildclient.

ALTCC

When the -C option is specified for COBOL compilation, buildclient normally uses the Oracle Tuxedo shell cobcc which in turn calls cob to produce the client executable. In order to allow for the specification of an alternate compiler, buildclient checks for the existence of an environment variable named ALTCC. If ALTCC does not exist in buildclient’s environment, or if it is the string "", buildclient uses cobcc. If ALTCC does exist in the environment, its value is taken to be the name of the compiler command to be executed.

Note:

On a Windows system, the ALTCC and ALTCFLAGS environment variables are not applicable and setting them will produce unexpected results. You must compile your application first using a COBOL compiler and then pass the resulting object file to the buildclient(1) command.

ALTCFLAGS

The environment variable ALTCFLAGS is taken to contain a set of additional arguments to be passed as part of the COBOL compiler command line when the -C option is specified. This is in addition to the command line option:

“-I${TUXDIR}/include”

This option is passed automatically by buildclient. When the -C option is used, putting compiler options and their arguments in the buildclient -f option generates errors; they must be put in ALTCFLAGS. If not set, the value is set to the same value used for CFLAGS, as specified above.

1. ALTCFLAGS only works for the MicroFocus COBOL compiler. For other supported COBOL compilers (i.e., IBMCOBOL or AccuCOBOL), CFLAGS is supported and is sufficient.
2. See the note under the description of the ALTCC environment variable.

COBOPT

The environment variable COBOPT is taken to contain a set of additional arguments to be used by the COBOL compiler, when the -C option is specified.

COBCPY

The environment variable COBCPY indicates which directories contain a set of COBOL copy files to be used by the COBOL compiler, when the -C option is specified.

TM_COB_STATIC

The environment variable TM_COB_STATIC indicates whether shared version or static version libcobatmi library to be linked by buildclient. The environment variable value may be “Yes” or “No”. If “Yes” is set, static version libcobatmi library is used; otherwise shared version is used. If the environment variable is not specified, the shared version libcobatmi library is used by default.

Note:

For Tuxedo releases prior 10.0, buildserver links to the static version libcobatmi library.

COB

The environment variable COB indicates which COBOL compiler is used. It supports two parameters: AcuCobol and IBMCobol.

If “AcuCobol” is specified, the ACUCOBOL compiler is used. If “IBMCobol” is specified, the IBMCOBOL compiler is used.

If no parameters are specified, the standard COBOL compiler is used.

TM_COB_VERSION

The environment variable TM_COB_VERSION indicates the ACUCOBOL compiler version. This environment variable takes effect only when -C option is specified and the environment variable COB is set to “AcuCobol”. The value format of the environment variable is “[0-9]+\.[0-9]”.

• If TM_COB_VERSION value is less than 7.0, buildclient generates old style ACUCOBOL stub code; otherwise buildclient generates new style ACUCOBOL stub code.
• If TM_COB_VERSION is not set, buildclient generates new style ACUCOBOL stub code by default.

TM_COB_CC_FILES

When ACUCOBOL compiler is used, only COBOL source files can be specified with -f option. If there are other user files to be passed to cc(1) in the compilation and link edit phases of buildclient first, before the Oracle Tuxedo ATMI libraries, these files must be specified with the environment variable TM_COB_CC_FILES. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. The environment variable takes effect only when -C option is specified and the environment variable COB is set to “AcuCobol”.

Note:

ACUCOBOL system libraries and object files used by ACUCOBOL CVM must be included in the file list.

ACUCOBOL

When ACUCOBOL is used for COBOL compilation, the environment variable ACUCOBOL indicates the ACUCOBOL installed directory so that ACUCOBOL system libraries and files can be found during the client compilation.

Note:

File direct.c is used by ACUCOBOL to access C external variables and functions in COBOL programs. If the programmer modified direct.c to support third party software, the modified direct.c must be stored under directory $ACUCOBOL/lib.

IBMCOBOL

When IBMCOBOL is used for COBOL compilation, the environment variable IBMCOBOL indicates the IBMCOBOL installed directory so that IBMCOBOL system libraries and files can be found during the client compilation.

Note:

Both IBM COBOL 2.0 and 3.1 do not support C compiler messages.

COBOL 2.0 returns an error when you specify "LANG=C" which causes the complier to terminate. COBOL 3.1 returns a warning.

Specify "LANG=en_US" when you want to use IBM COBOL 2.0.

IBM COBOL 3.1 does not require "LANG=en_US".

LD_LIBRARY_PATH (UNIX systems)

The environment variable LD_LIBRARY_PATH indicates which directories contain shared objects to be used by the COBOL compiler, in addition to the Oracle Tuxedo system shared objects. Some UNIX systems require different environment variables: for HP-UX systems, use the SHLIB_PATH environment variable; for AIX, use LIBPATH.

LIB(Windows NT systems)

Indicates a list of directories within which to find libraries. A semicolon (;) is used to separate the list of directories.

The buildclient compilation tool is supported on the following platforms:

• Any platform on which the Oracle Tuxedo ATMI server environment is supported
• Any Workstation platform running a 32-bit Windows operating system

Filenames specified in the buildclient command line must conform to the syntax and semantics of the resident operating system.

Listing 1 BUILDCLIENT COBOL Example

CC=ncc CFLAGS="-I /APPDIR/include"; export CC CFLAGS
buildclient -o empclient -f emp.c -f "userlib1.a userlib2.a"

COBCPY=$TUXDIR/cobinclude
COBOPT="-C ANS85 -C ALIGN=8 -C NOIBMCOMP -C TRUNC=ANSI -C OSEXT=cbl"
COBDIR=/usr/lib/cobol LD_LIBRARY_PATH=$COBDIR/coblib:$TUXDIR/lib
export COBOPT COBCPY COBDIR LD_LIBRARY_PATH
buildclient -C -o empclient -f name.cbl -f "userlib1.a userlib2.a"

Listing 2 BUILDCLIENT ACUCOBOL Example

TUXDIR=/opt/tuxedo10.0
TM_COB_STATIC=no
COB=AcuCobol
COBCPY=$TUXDIR/cobinclude
COBOPT="-Ca -v -w -Ga -Dw64 -Dl8 -Da8"
TM_COB_VERSION=7.2
ACUCOBOL=/opt/AcuCobol-7.2.1
TM_COB_CC_FILES="-lruncbl -lclnt -lacvt -lfsi -laregex -lacuterm -lextfh -laxml -lexpat -lvision -lesql -lacme -lz -lm"
LD_LIBRARY_PATH=$ACUCOBOL/lib:$TUXDIR/lib
export TUXDIR TM_COB_STATIC COB COBCPY COBOPT TM_COB_VERSION ACUCOBOL TM_COB_CC_FILES LD_LIBRARY_PATH
buildclient -C -o CSIMPCL -f CSIMPCL.cbl

Listing 3 BUILDCLIENT IBMCOBOL Example

TUXDIR=/opt/tuxedo10.0
TM_COB_STATIC=no
COB=IBMCobol
IBMCOBOL=/usr/lpp/cobol
COBCPY=$TUXDIR/cobinclude
COBOPT="-Ca -v -w -Ga -Dw64 -Dl8 -Da8" LD_LIBRARY_PATH=$IBMCOBOL/lib:$TUXDIR/lib
export TUXDIR TM_COB_STATIC COB COBCPY COBOPT IBMCOBOL LD_LIBRARY_PATH
buildclient -C -o CSIMPCL -f CSIMPCL.cbl

buildmqadapter— Link TM_MQI, TM_MQO, and TMQUEUE_MQM servers

buildmqadapter [-v] [-r rmname][-c] [-t]

buildmqadapter builds the TM_MQI, TM_MQO, and TMQUEUE_MQM servers and installs them in $TUXDIR/bin/TM_MQI,$TUXDIR/bin/TM_MQO, and $TUXDIR/bin/TMQUEUE_MQM.

The servers built by buildmqadapter are used by the Tuxedo MQ Adapter to interact with IBM WebSphere MQ as described in the Oracle MQ Adapter for Tuxedo 11gR1 Users Guide.

The user must have permissions to create or overwrite the MQ Adapter server files.

buildmqadapter invokes the buildserver command to build each of the MQ Adapter servers.

Building the MQ Adapter server files using buildmqadapter instead of distributing prelinked objects allows the Tuxedo administrator to configure:

• Whether the MQ adapter servers are to be linked with WebSphere MQ Server libraries or with WedSphere MQ client libraries.
• Whether the MQ adapter servers are to be linked with the dynamic XA switch MQRMIXASwitchDynamic or the static RM switch MQRMIXASwitch.
• The patch level and release of WebSphere MQ libraries to link with.

buildmqadapter does not build the TMS server for the MQ resource manager, and the Tuxedo administrator will need to execute buildtms at some time in order to build the WebSphere MQ TMS server.

v

Specifies that buildmqadapter must work in verbose mode. In particular, it writes the buildserver command to its standard output and specifies the -v option to buildserver.

-r rm_name

Specifies the resource manager name associated with the MQ Adapter servers. The value rm_name must appear in the resource manager table located at $TUXDIR/udataobj/RM. The entry associated with the rm_name value is used to include the correct libraries for the resource manager automatically and properly to set up the interface between the transaction manager and resource manager (using the xa_switch_t structure). The default value for this parameter is MQSeries_XA_RMI.

-c

Specifies building MQ Adapter with WebSphere MQ client library.

-t

Specifies building multi-threaded servers. This option only takes effect on TM_MQI server.

buildmqadapter uses the buildserver command to produce the output files. buildserver uses the CC and CFLAGS environment variables, if set, for the compiler and compiler flags, respectively. See buildserver(1) for further details.

buildmqadapter -v

buildnetclient—Constructs an Oracle Tuxedo .NET Workstation Client module.

buildnetclient is a utility used to construct a Tuxedo .NET Workstation Client application. This command combines the files specified by the .cs source file arguments, .dll assembly files, and .netmodule module files with the Tuxedo .NET Workstation Client wrapper libraries to form a client application. The client application is then built using the C# compiler (csc.exe) provided by Microsoft’s .NET Framework environment.

Users may specify options to be passed to the C# compiler by setting the csflag option.

-v

Specifies that the buildnetclient command must work in verbose mode. In particular, it writes the compile command to its standard output.

-o outfile

Specifies the name of the client application generated by this command. If the name is not supplied, the application file is named after the C# source file which has a class containing a static method Main inside, and the file name extension is dependent on the operating system for an application (on a Windows system the extension would be .exe).

-csflag flagstring

Indicates any arguments that are passed as part of the C# compiler command line for any files with a .cs file extension. Multiple C# compiler options may be specified if they are enclosed in quotation marks and are separated by white space.

.cs source

Specifies any C# source files with a .cs file extension which are needed to build the application file.

.dll assembly files

Specifies any .NET assembly files with a .dll file extension which are referenced by the files in the .cs source files list to build the application file.

.netmodule module files

Specifies any .NET module files with a .netmodule file extension which are needed to build the application file.

buildnetclient analyzes the arguments passed to it via command line and constructs another valid command line to invoke the C# compiler to build the application executable.

For example, [buildnetclient -o t1.exe, t1.cs] is translated by buildnetclient to csc /out:t1.exe/t:exe /r:%TUXDIR%\bin\libwscdnet.dll t1.cs on Windows system.

The following example builds two C# source files t1.cs, t2.cs and a module file t3.netmodule together into a executable assembly first.exe. In this example, t1.cs calls methods provided by a library assembly func.dll which is located in the same directory with the above files.

[buildnetclient -o first.exe func.dll t1.cs t3.netmodule t2.cs]

buildobjclient—Constructs a CORBA client application.

buildobjclient [-v][-oname] [-f
         firstfile
            -syntax]

         [-l lastfile
            -syntax] -P

Use the buildobjclient command to construct a CORBA client application. The command combines the files specified in the -f and -l options with the standard CORBA libraries to form a client application. The client application is built using the default C++ language compile command defined for the operating system in use.

All specified .c and .cpp files are compiled in one invocation of the compilation system for the operating system in use. Users may specify the compiler to invoke by setting the CC environment variable to the name of the compiler. If the CC environment variable is not defined when buildobjclient is invoked, the default C++ language compile command for the operating system in use will be invoked to compile all .c and .cpp files.

Users may specify options to be passed to the compiler by setting the CFLAGS or the CPPFLAGS environment variables. If CFLAGS is not defined when buildobjclient is invoked, the buildobjclient command uses the value of CPPFLAGS if that variable is defined.

-v

Specifies that the buildobjclient command must work in verbose mode. In particular, it writes the compile command to its standard output.

-o name

Specifies the name of the client application generated by this command. If the name is not supplied, the application file is named client<.type>, where type is an extension that is dependent on the operating system for an application (for example, on a UNIX system, there would not be a type; on a Windows system, the type would be .EXE).

-f firstfile-syntax

Specifies a file to be included first in the compile and link phases of the buildobjclient command. The specified file is included before the CORBA libraries are included. There are three ways of specifying a file or files, as shown in the following table.

Table 1-2 Specifying the First Filename(s)

Filename Specification	Definition
-f firstfile	One file is specified
-f "file.cpp file2.cpp file3.cpp ... "	Multiple files may be specified if names are enclosed in quotation marks and are separated by white space.

Note:

• Filenames that include spaces are not supported.
• The -f option may be specified multiple times.

-l lastfile-syntax

Specifies a file to be included last in the compile and link phases of the buildobjclient command. The specified file is included after the CORBA libraries are included. There are three ways of specifying a file, as shown in the following table.

Table 1-3 Specifying the Last Filename(s)

Filename Specification	Definition
-l lastfile	One file is specified.
-l "file.cpp file2.cpp file3.cpp ... "	Multiple files may be specified if their names are enclosed in quotation marks and are separated by white space.

Note:

The -l option may be specified multiple times.

-P

Specifies that the appropriate POA libraries must be linked into the image (that is, libraries that allow a client to also function as a server). The resulting image can act as a server and can use the Callbacks wrapper class for creating objects. The resulting joint client/server cannot take advantage of the object state management and transaction management provided by the Oracle Tuxedo TP Framework. The -P switch must have been passed to the IDL compiler when generating the client. Use buildobjserver to build a server with all the support provided by the TP Framework. The default is to not link in the server libraries; that is, the default is to create a client only, not a joint client/server.

-h or -?

Provides help that explains the usage of the buildobjclient command. No other action results.

TUXDIR

Finds the CORBA libraries and include files to use when compiling the client applications.

CC

Indicates the compiler to use to compile all files with .c or .cpp file extensions. If not defined, the default C++ language compile command for the operating system in use will be invoked to compile all .c and .cpp files.

CFLAGS

Indicates any arguments that are passed as part of the compiler command line for any files with a .c or .cpp file extensions. If CFLAGS does not exist in the buildobjclient command environment, the buildobjclient command checks for the CPPFLAGS environment variable.

CPPFLAGS

Note:

Arguments passed by the CFLAGS environment variable take priority over the CPPFLAGS variable.

Contains a set of arguments that are passed as part of the compiler command line for any files with a .c or .cpp file extensions.

This is in addition to the command line option "-I$(TUXDIR)/include" for UNIX systems or the command line option /I%TUXDIR%\include for Windows systems, which is passed automatically by the buildobjclient command. If CPPFLAGS does not exist in the buildobjclient command environment, no compiler commands are added.

LD_LIBRARY_PATH(UNIX systems)

Indicates which directories contain shared objects to be used by the compiler, in addition to the objects shared by the CORBA software. A colon (:) is used to separate the list of directories. Some UNIX systems require different environment variables: for HP-UX systems, use the SHLIB_PATH environment variable; for AIX, use LIBPATH.

LIB

Indicates a list of directories within which to find libraries. A semicolon (;) is used to separate the list of directories.

The buildobjclient command is not supported on client-only CORBA systems.

The following example builds a CORBA client application on a Windows system:

set CPPFLAGS=-I%APPDIR%\include
buildobjclient -o empclient.exe -f emp_c.cpp -l userlib1.lib

The following example builds a CORBA client application on a UNIX system using the c shell:

setenv CPPFLAGS=$APPDIR/include
buildobjclient -o empclient -f emp_c.cpp -l userlib1.a

buildobjserver—Constructs a CORBA server application.

buildobjserver [-v] [-o name][-ffirstfile-syntax]
[-llastfile-syntax] [-rrmname][-t]

Use the buildobjserver command to construct a CORBA server application. The command combines the files specified with the -f and -l options with the main routine and the standard CORBA libraries to form a server application. The server application is built using the default C++ compiler provided for the platform.

All specified .c and .cpp files are compiled in one invocation of the compilation system for the operating system in use. Users may specify the compiler to be invoked by setting the CC environment variable to the name of the compiler. If the CC environment variable is not defined when buildobjserver is invoked, the default C++ language compile command for the operating system in use is invoked to compile all .c and .cpp files.

Users may specify options to be passed to the compiler by setting the CFLAGS or the CPPFLAGS environment variable. If CFLAGS is not defined but CPPFLAGS is defined when buildobjserver is invoked, the command uses the value of CPPFLAGS.

-v

Specifies that the buildobjserver command must work in verbose mode, and it writes the compile command to standard output.

-o name

Specifies the name of the server application generated by this command. If a name is not supplied, the application file is named server. type , where type is an extension that indicates which operating system is being used for the application. For example, an application that is called server on a UNIX system is called server.EXE on a Windows NT system.

-f firstfile-syntax

Specifies the file to be included first (that is, before the CORBA libraries) in the compile and link phases of the buildobjserver command. For a description of the three ways to specify files, see the table entitled Table 1-2.

-l lastfile-syntax

Specifies the file to be included last (that is, after the CORBA libraries) in the compile and link phases of the buildobjserver command. For a description of the three ways to specify files, see the table entitled Table 1-3.

-r rmname

Specifies the resource manager associated with this server. The value rmname must appear in the resource manager table located in $TUXDIR/udataobj/RM on UNIX systems or %TUXDIR%\udataobj\RM on Windows NT systems.

Each entry in this file is of the form: rmname:rmstructure_name:library_names

Using the rmname value, the entry in $TUXDIR/udataobj/RM or %TUXDIR%\udataobj\RM automatically includes the associated libraries for the resource manager and sets up the interface between the transaction manager and the resource manager. The value TUXEDO/SQL includes the libraries for the Oracle Tuxedo System/SQL resource manager. Other values can be specified as they are added to the resource manager table. If the -roption is not specified, the null resource manager is used by default.

-h or -?

Invokes help: information that is useful when running thebuildobjserver command. No other action results.

-t

Invokes multithreading in the CORBA server application being built. When you specify this option, you must also set the MAXDISPATCHTHREADS parameter in the UBBCONFIG file to a value greater than 1. If you do not, your CORBA server runs as a single-threaded application.

TUXDIR

Finds the CORBA libraries and include files to use when compiling the server application.

CC

Indicates the compiler to use to compile all files with .c or .cpp file extensions that are passed in through the –l or -f option.

CFLAGS

Specifies any arguments that are passed as part of the compiler command line for any files with .c or .cpp file extensions. If CFLAGS is not available in the buildobjserver command environment, the buildobjserver command checks for the CPPFLAGS environment variable.

CPPFLAGS

Note:

Arguments passed by the CFLAGS environment variable take priority over the CPPFLAGS environment variable.

Contains a set of arguments that are passed as part of the compiler command line for any files with a .c or .cpp file extension. This option is used in addition to the command-line option -I$TUXDIR/include on a UNIX system, or the command-line option /I%TUXDIR%\include on a Windows NT system, which is passed automatically by the buildobjserver command. If CPPFLAGS is not available in the buildobjserver command environment, no compiler commands are added.

LD_LIBRARY_PATH (UNIX systems)

List of directories that contain shared objects to be used by the compiler, in addition to CORBA shared objects. A colon (:) is used to separate names of directories. Some UNIX systems require different environment variables: for HP-UX systems, use the SHLIB_PATH environment variable; for AIX, use LIBPATH.

LIB (Windows NT systems)

List of directories in which libraries reside. A semicolon (;) is used to separate names of directories.

The buildobjserver command is not supported on client-only CORBA systems.

The following example builds a CORBA server application on a UNIX system using the emp_s.cpp and emp_i.cpp files:

buildobjserver -r TUXEDO/SQL -o unobserved 
-f “emp_s.cpp emp_i.cpp”

The following example shows how to use the CC and CFLAGS environment variables with the buildobjserver command. The example also shows how to link in the math library, using the -f and -lm options, in a Bourne or Korn shell (on a UNIX system):

CFLAGS=-g CC=/bin/cc \ 
buildobjserver -r TUXEDO/SQL -o TLR -f TLR.o -f util.o -l -lm

The following example shows how to use the buildobjserver command on a UNIX system with no resource manager specified:

buildobjserver -o PRINTER -f PRINTER.o

The following sections show sample RM files for all supported operating system platforms:

Windows NT

Oracle_XA;xaosw;C:\Orant\rdbms73\xa\xa73.lib
C:\Orant\pro22\lib\msvc\sqllib18.lib

UNIX

Oracle_XA:xaosw:-L$ORACLE_HOME/rdbms/lib
-L$ORACLE_HOME/precomp/lib -lc
-L/home4/m01/app/oracle/product/7.3.2/lib -lsql -lclntsh
-lsqlnet -lncr -lcommon -lgeneric -lepc -lnlsrtl3 -lc3v6
-lcore3 -lsocket -lnsl -lm -ldl -lthread

Digital UNIX

Oracle_XA:xaosw:-L${ORACLE_HOME}/lib -lxa
${ORACLE_HOME}/lib/libsql.a -lsqlnet -lncr -lsqlnet
${ORACLE_HOME}/lib/libclient.a -lcommon -lgeneric -lsqlnet
-lncr -lsqlnet ${ORACLE_HOME}/lib/libclient.a -lcommon
-lgeneric -lepc -lepcpt -lnlsrtl3 -lc3v6 -lcore3
-lnlsrtl3 -lcore3 -lnlsrtl3 -lm

AIX

Oracle_XA:xaosw:-L${ORACLE_HOME}/lib -lxa -lsql
-lsqlnet
-lncr -lclient -lcommon -lgeneric -lepc -lnlsrtl3 -lc3v6
-lcore3 -lm -lld

HP-UX with Oracle 8.04

Oracle_XA:xaosw:-L${ORACLE_HOME}/lib -lclntsh

buildserver—Constructs an Oracle Tuxedo ATMI server load module.

buildserver [-C] [-M] [-s services[:func[()]]][-v] [-o outfile] [-f firstfiles] [-l lastfiles] [{-r|-g} rmname] [-E envlabel][-t] 
[-z]

buildserver is used to construct an Oracle Tuxedo ATMI server load module. The command combines the files supplied by the -f and -l options with the standard server main routine and the standard Oracle Tuxedo ATMI libraries to form a load module. The load module is built by the cc(1) command, which buildserver invokes. (See cc(1) in any UNIX system reference manual.) The options to buildserver have the following meaning:

-v

Specifies that buildserver must work in verbose mode. In particular, it writes the compilation command to its standard output.

-o outfile

Specifies the name of the file the output load module is to have. If not supplied, the load module is named SERVER.

-f firstfiles

Specifies one or more user files to be included in the compilation and link edit phases of buildserver first, before the Oracle Tuxedo ATMI libraries. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. This option may be specified multiple times. The CFLAGS and ALTCFLAGS environment variables, described below, must be used to include any compiler options and their arguments.

If -C option is specified and the environment variable COB is set to “AcuCobol”, this option only accepts COBOL source files. Other user files, such as library files, C source files, etc, must be specified with environment variable “TM_COB_CC_FILES”. See below “Environment Variable” section.

-l lastfiles

Specifies one or more user files to be included in the compilation and link edit phases of buildserver last, after the Oracle Tuxedo ATMI libraries. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. This option may be specified multiple times.

-M

Specifies multiple resource managers associated with this server. If you want your server to be associated with multiple XA complaint resource managers, this option is mandatory. If this option is not specified and you try to boot a server with a configuration file in which this server is specified in a non-multiple resource manager server group, a warning message is printed in the user log and the sever reverts to a general server associating with one resource manager if the "-r" option is specified when executing buildserver command.

-r rmname

Specifies the resource manager associated with this server. The value rmname must appear in the resource manager table located in $TUXDIR/udataobj/RM. Each line in this file is of the form:

rmname:rmstructure_name:library_names

(See buildtms(1) for further details.) Using the rmname value, the entry in $TUXDIR/udataobj/RM is used to include the associated libraries for the resource manager automatically and to set up the interface between the transaction manager and resource manager properly. Other values can be specified as they are added to the resource manager table. If the -r option is not specified, the default is to use the null resource manager. Refer to the UBBCONFIG(5) reference page.

If -M is specified, buildserver allows at most 32 types of resource managers. If more than 32 resource managers are specified with the -r option, the previous resource manager is replaced and a warning message is printed.

If a duplicate resource manager name is specified, then is be ignored and a warning message is printed.

buildserver ignores duplicate library by comparing the library_names configured in RM file and prints a warning message.

-s { @filename | service[,service...][:func] | :func } ]

Specifies the names of services that can be advertised when the server is booted. Service names (and implicit function names) must be less than or equal to 127 characters in length. An explicit function name (that is, a name specified after a colon) can be up to 128 characters in length. Names longer than these limits are truncated with a warning message. When retrieved by tmadmin(1) in Introduction to Oracle Tuxedo Commands or TM_MIB(5), only the first 127 characters of a name are displayed. (See servopts(5).) All functions that can be associated with a service must be specified with this option. In the most common case, a service is performed by a function that carries the same name; that is, the x service is performed by function x. For example, the following specification builds the associated server with services x, y, and z, each to be processed by a function of the same name:

-s x,y,z

In other cases, a service (or several services) may be performed by a function of a different name. The following specification builds the associated server with services x, y, and z, each to be processed by the function abc:

-s x,y,z:abc

Spaces are not allowed between commas. Function name is preceded by a colon. In another case, the service name may not be known until run time. Any function that can have a service associated with it must be specified to buildserver. To specify a function that can have a service name mapped to it, put a colon in front of the function name. For example, the following specification builds the server with a function pqr, which can have a service association. tpadvertise(3c) could be used to map a service name to the pqr function.

-s :pqr

A filename can be specified with the -s option by prefacing the filename with the ‘@’ character. Each line of this file is treated as an argument to the -s option. You may put comments in this file. All comments must start with the ‘#’ character. This file can be used to specify all the functions in the server that may have services mapped to them.

The -s option may appear several times. Note that services beginning with the ‘.’ character are reserved for system use, and buildserver will fail if the -s option is used to include such a service in the server.

-c

Specifies COBOL compilation.

buildserver normally uses the cc command to produce the a.out. In order to allow for the specification of an alternate compiler, buildserver checks for the existence of a shell variable named CC. If CC does not exist in buildservercs environment, or if it is the string "", buildserver will use cc as the compiler. If CC does exist in the environment, its value is taken to be the name of the compiler to be executed. Likewise, the shell variable CFLAGS is taken to contain a set of parameters to be passed to the compiler.

-k

Keeps the server main stub. buildserver generates a main stub with data structures such as the service table and a main() function. This is normally compiled and then removed when the server is built. This option indicates that the source file must be kept (to see what the source filename is, use the -v option).

Note: The generated contents of this file may change from release to release; DO NOT count on the data structures and interfaces exposed in this file. This option is provided to aid in debugging of build problems.

-t

Specifies multithreading. If you want your servers to be multithreaded, this option is mandatory. If this option is not specified and you try to boot a server with a configuration file in which the value of MAXDISPATCHTRHREADS is greater than 1, a warning message is printed in the user log and the server reverts to single-threaded operation.

The purpose of this option is to prevent an administrator from trying to boot, as a multithreaded server, a server that is not programmed in a thread-safe manner.

-z

Specifies the __stdcall calling convention for the XA switch interfaces.

TUXDIR

buildserver uses the environment variable TUXDIR to find the Oracle Tuxedo ATMI libraries and include files to use during compilation of the server process.

CC

buildserver normally uses the default C language compilation command to produce the server executable. The default C language compilation command is defined for each supported operating system platform and is defined as cc(1) for the UNIX system. In order to allow for the specification of an alternate compiler, buildserver checks for the existence of an environment variable named CC. If CC does not exist in the buildserver environment, or if it is the string "", buildserver will use the default C language compiler. If CC does exist in the environment, its value is taken to be the name of the compiler to be used.

CFLAGS

The environment variable CFLAGS is taken to contain a set of arguments to be passed as part of the compiler command line. This is in addition to the command line option "-I${TUXDIR}/include" passed automatically by buildserver. If CFLAGS does not exist in buildserver’s environment, or if it is the string "", no compiler command line arguments are added by buildserver.

ALTCC

When the -C option is specified for COBOL compilation, buildserver normally uses the Oracle Tuxedo shell cobcc(1) in Introduction to Oracle Tuxedo Commands which in turn calls cob to produce the server executable. In order to allow for the specification of an alternate compiler, buildserver checks for the existence of an environment variable named ALTCC. If ALTCC does not exist in buildserver’s environment, or if it is the string "", buildserver will use cobcc. If ALTCC does exist in the environment, its value is taken to be the name of the compiler command to be executed.

Note:

On a Windows system, the ALTCC and ALTCFLAGS environment variables are not applicable and setting them will produce unexpected results. You must compile your application first using a COBOL compiler and then pass the resulting object file to the buildserver(1) command.

ALTCFLAGS

The environment variable ALTCFLAGS is taken to contain a set of additional arguments to be passed as part of the COBOL compiler command line when the -C option is specified. This is in addition to the command line option "-I${TUXDIR}/include" passed automatically by buildserver. When the -C option is used, putting compiler options and their arguments in the buildserver -f option will generate errors; they must be put in ALTCFLAGS. If not set, the value is set to the same value used for CFLAGS, as specified above.

Note:

1. ALTCFLAGS only works for the MicroFocus COBOL compiler. For other supported COBOL compilers (i.e., IBMCOBOL or AccuCOBOL), CFLAGS is supported and is sufficient.
2. See the note under the description of the ALTCC environment variable.

COBOPT

The environment variable COBOPT is taken to contain a set of additional arguments to be used by the COBOL compiler, when the -C option is specified.

COBCPY

The environment variable COBCPY indicates which directories contain a set of COBOL copy files to be used by the COBOL compiler, when the -C option is specified.

TM_COB_STATIC

The environment variable TM_COB_STATIC indicates whether shared version or static version libcobatmi library to be linked by buildserver. The environment variable value may be “Yes” or “No”. If “Yes” is set, static version libcobatmi library is used; otherwise shared version is used. If the environment variable is not specified, the shared version libcobatmi library is used by default.

Note:

For Tuxedo releases prior 10.0, buildserver links to the static version libcobatmi library.

COB

The environment variable COB indicates which COBOL compiler is used. It supports two parameters: AcuCobol and IBMCobol.

If “AcuCobol” is specified, the ACUCOBOL compiler is used. If “IBMCobol” is specified, the IBMCOBOL compiler is used.

If no parameters are specified, the standard COBOL compiler is used.

TM_COB_VERSION

The environment variable TM_COB_VERSION indicates the ACUCOBOL compiler version. This environment variable takes effect only when -C option is specified and the environment variable COB is set to “AcuCobol”. The value format of the environment variable is “[0-9]+\.[0-9]”.

• If TM_COB_VERSION value is less than 7.0, buildserver generates old style ACUCOBOL stub code; otherwise buildserver generates new style ACUCOBOL stub code.
• If TM_COB_VERSION is not set, buildserver generates new style ACUCOBOL stub code by default.

TM_COB_CC_FILES

When ACUCOBOL compiler is used, only COBOL source files can be specified with -f option. If there are other user files to be passed to cc(1) in the compilation and link edit phases of buildserver first, before the Oracle Tuxedo ATMI libraries, these files must be specified with the environment variable TM_COB_CC_FILES. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. The environment variable takes effect only when -C option is specified and the environment variable COB is set to “AcuCobol”.

Note that ACUCOBOL system libraries and object files used by ACUCOBOL CVM must be included in the file list.

ACUCOBOL

When ACUCOBOL is used for COBOL compilation, the environment variable ACUCOBOL indicates the ACUCOBOL installed directory so that ACUCOBOL system libraries and files can be found during the server process compilation.

When ACUCOBOL is used for COBOL compilation, the environment variable ACUCOBOL indicates the ACUCOBOL installed directory so that ACUCOBOL system libraries and files can be found during the server process compilation.

Note: File direct.c is used by ACUCOBOL to access C external variables and functions in COBOL programs. If the programmer modified direct.c to support third party software, the modified direct.c must be stored under directory $ACUCOBOL/lib.

IBMCOBOL

When IBMCOBOL is used for COBOL compilation, the environment variable IBMCOBOL indicates the IBMCOBOL installed directory so that IBMCOBOL system libraries and files can be found during the server compilation.

Note: Both IBM COBOL 2.0 and 3.1 do not support C compiler messages. COBOL 2.0 returns an error when you specify "LANG=C" which causes the complier to terminate. COBOL 3.1 returns a warning. Specify "LANG=en_US" when you want to use IBM COBOL 2.0. IBM COBOL 3.1 does not require "LANG=en_US".

TM_COBOLIT_VERSION

TM_COBOLIT_VERSION is taken to judge the COBOL compiler version. Set this environment variable when using COBOL-IT compiler 3.5 or higher; otherwise, the build will fail. Once you set it, Tuxedo will automatically specify COBITOPT=-fno-main to compile COBOL main function.

LD_LIBRARY_PATH(UNIX systems)

The environment variable LD_LIBRARY_PATH indicates which directories contain shared objects to be used by the COBOL compiler, in addition to the Oracle Tuxedo shared objects. Some UNIX systems require different environment variables: for HP-UX systems, use the SHLIB_PATH environment variable; for AIX, use LIBPATH.

LIB (Windows NT systems)

Indicates a list of directories within which to find libraries. A semicolon (;) is used to separate the list of directories.

In earlier releases, the -g option was allowed to specify a genoption of sql or database. For upward compatibility, this option is a synonym for the -r option.

The buildserver compilation tool is supported on any platform on which the Oracle Tuxedo ATMI server environment is supported. RM XA libraries are not supported on the Windows platform.

Some compilation systems may require some code to be executed within the main(). For example, this could be used to initialize constructors in C++ or initialize the library for COBOL. A general mechanism is available for including application code in the server main() immediately after any variable declarations and before any executable statements. This will allow for the application to declare variables and execute statements in one block of code. The application exit is defined as follows: #ifdef TMMAINEXIT #include "mainexit.h" #endif. To use this feature, the application must include "-DTMMAINEXIT" in the ALTCFLAGS (for COBOL) or CFLAGS (for C) environment variables and provide a mainexit.h in the current directory (or use the -I include option to include it from another directory).

For example, Micro Focus Cobol V3.2.x with a PRN number with the last digits greater than 11.03 requires that cobinit() be called in main before any COBOL routines, if using shared libraries. This can be accomplished by creating a mainexit.h file with a call to cobinit() (possibly preceded by a function prototype) and following the procedure above.

For the server compiled using ACUCOBOL compiler, servopts(5) has special meaning. The uargs (value specified after '--') of the server CLOPT parameter are passed as arguments to acu_initv() subroutine to start ACUCOBOL CVM.

The following example shows how to specify the resource manager (-r TUXEDO/SQL) libraries on the buildserver command line:

buildserver -r TUXEDO/SQL -s OPEN_ACCT -s CLOSE_ACCT -o ACCT
-f ACCT.o -f appinit.o -f util.o

The following example shows how buildserver can be supplied CC and CFLAGS variables and how -f can be used to supply a -lm option to the CC line to link in the math library:

CFLAGS=-g CC=/bin/cc buildserver -r TUXEDO/SQL -s DEPOSIT
-s WITHDRAWAL -s INQUIRY -o TLR -f TLR.o -f util.o -f -lm

The following example shows use of the buildserver command with no resource manager specified: buildserver -s PRINTER -o PRINTER -f PRINTER.o

Listing 4 shows a general COBOL compiler example.

Listing 4 BUILDSERVER COBOL Example

COBCPY=$TUXDIR/cobinclude
COBOPT="-C ANS85 -C ALIGN=8 -C NOIBMCOMP -C TRUNC=ANSI -C OSEXT=cbl"
COBDIR=/usr/lib/cobol
LD_LIBRARY_PATH=$COBDIR/coblib
export COBOPT COBCPY COBDIR LD_LIBRARY_PATH
buildserver -C -r TUXEDO/SQL -s OPEN_ACCT -s CLOSE_ACCT -o ACCT -f ACCT.o -f appinit.o -f util.o

Listing 5 shows an ACUCOBOL compiler example.

Listing 5 BUILDSERVER ACUCOBOL Example

TM_COB_STATIC=no
COB=AcuCobol
COBCPY=$TUXDIR/cobinclude
COBOPT="-Ca -v -w -Ga -Dw64 -Dl8 -Da8"
TM_COB_VERSION=7.2
ACUCOBOL=/opt/AcuCobol-7.2.1
TM_COB_CC_FILES="-lruncbl -lclnt -lacvt -lfsi -laregex -lacuterm -lextfh -laxml -lexpat -lvision -lesql -lacme -lz -lm"
LD_LIBRARY_PATH=$ACUCOBOL/lib:$TUXDIR/lib
export TUXDIR TM_COB_STATIC COB COBCPY COBOPT TM_COB_VERSION
ACUCOBOL TM_COB_CC_FILES LD_LIBRARY_PATH
buildserver -C -sTOUPPER -sTOLOWER -o CSIMPSRV -f CTOUPPER.cbl -f CLOWER.cbl -f TPSVRINIT.cbl

Listing 6 shows an IBMCOBOL compiler example.

Listing 6 BUILDSERVER IBMCOBOL Example

TUXDIR=/opt/tuxedo10.0
TM_COB_STATIC=no
COB=IBMCobol
IBMCOBOL=/usr/lpp/cobol
COBCPY=$TUXDIR/cobinclude
COBOPT="-Ca -v -w -Ga -Dw64 -Dl8 -Da8"
LD_LIBRARY_PATH=$IBMCOBOL/lib:$TUXDIR/lib
export TUXDIR TM_COB_STATIC COB COBCPY COBOPT IBMCOBOL LD_LIBRARY_PATH
buildserver -C -sTOUPPER -sTOLOWER -o CSIMPSRV -f CTOUPPER.cbl -f CLOWER.cbl -f TPSVRINIT.cbl

buildTM_MQI(1)—Links the TM_MQI server

buildTM_MQO(1) —Links the TM_MQO server

buildTMQUEUE_MQM(1) —Links the TMQUEUE_MQM server

buildTM_MQI [-v] [-r rmname] [-c] [-t] [-o outfile]
buildTM_MQO [-v] [-r rmname] [-c] [-t] [-o outfile]
buildTMQUEUE_MQM [-v] [-r rmname] [-c] [-t] [-o outfile]

These commands build one of three TM_MQI, TM_MQO, or TMQUEUE_MQM servers. The default output location is $TUXDIR/bin/TM_MQI, $TUXDIR/bin/TM_MQO, or $TUXDIR/bin/TMQUEUE_MQM. This may be changed using the -o option.

The servers built by these commands are used by the Tuxedo MQ Adapter to interact with IBM WebSphere MQ as described in the Oracle MQ Adapter for Tuxedo 10.0 User Guide.

The user must have permissions to create or overwrite the server output file.

These commands invoke buildserver to build the appropriate MQ Adapter server.

Building the MQ Adapter server files using these commands instead of distributing prelinked objects allows the Tuxedo administrator to configure:

• Whether the MQ adapter servers are to be linked with WebSphere MQ Server libraries or with WedSphere MQ client libraries.
• Whether the MQ adapter servers are to be linked with the dynamic XA switch MQRMIXASwitchDynamic or the static RM switch MQRMIXASwitch.
• The patch level and release of WebSphere MQ libraries to link with.

In addition to building the MQ Adapter servers, the system administrator will need to execute buildtms at some time in order to build the WebSphere MQ TMS server.

-v

Specifies that the command must work in verbose mode. In particular, the command writes the buildserver command to its standard output and specifies the -v option to buildserver.

-r rm_name

Specifies the resource manager name associated with the MQ Adapter servers. The value rm_name must appear in the resource manager table located at $TUXDIR/udataobj/RM. The entry associated with the rm_name value is used to include the correct libraries for the resource manager automatically and properly to set up the interface between the transaction manager and resource manager (using the xa_switch_t structure). The default value for this parameter is MQSeries_XA_RMI.

-c

Specifies building MQ Adapter with WebSphere MQ client library.

-t

Specifies building multi-threaded servers. This option takes effect only on TM_MQI server.

-o outfile

Specifies the name of the file the output load module is to have. If not specified, the default is $TUXDIR/bin/TM_MQI, $TUXDIR/bin/TM_MQO, or $TUXDIR/bin/TMQUEUE_MQM.

buildTM_MQI -v -o $TUXDIR/bin/TM_MQI
buildTM_MQO -v -o $TUXDIR/bin/TM_MQO
buildTMQUEUE_MQM -v -o $TUXDIR/bin/TMQUEUE_MQM

buildtms—Constructs a transaction manager server load module.

buildtms [ -v ] -o name-rrm_name [-z]

buildtms is used to construct a transaction manager server load module.

While several TM servers are provided with the Oracle Tuxedo system, new resource managers may be provided to work with the Oracle Tuxedo system for distributed transaction processing. The resource manager must conform to the X/OPEN XA interface. The following four items must be published by the resource manager vendor: the name of the structure of type xa_switch_t that contains the name of the resource manager, flags indicating capabilities of the resource manager, and function pointers for the actual XA functions; the name of the resource manager that is contained in the name element of the xa_switch_t structure; the name of the object files that provide the services of the XA interface and supporting software; and the format of the information string supplied to the OPENINFO and CLOSEINFO parameters in the UBBCONFIG configuration file. See UBBCONFIG(5).

When integrating a new resource manager into the Oracle Tuxedo system, the file $TUXDIR/udataobj/RM must be updated to include the information about the resource manager. The format of this file is

rm_name :rm_structure_name:library_names

where rm_name is the resource manager name, rm_structure_name is the name of the xa_switch_t structure, and library_names is the list of object files for the resource manager. White space (tabs and/or spaces) is allowed before and after each of the values and may be embedded within the library_names . The colon (:) character may not be embedded within any of the values. Lines beginning with a pound sign (#) are treated as comments and are ignored.

A transaction manager server for the new resource manager must be built using buildtms and installed in $TUXDIR/bin. buildtms uses the buildserver(1) command to build the resulting a.out. The options to buildtms have the following meaning:

-v

Specifies that buildtms must work in verbose mode. In particular, it writes the buildserver command to its standard output and specifies the -v option to buildserver.

-o name

Specifies the name of the file the output load module is to have.

-r rm_name

Specifies the resource manager associated with this server. The value rm_name must appear in the resource manager table located in $TUXDIR/udataobj/RM. The entry associated with the rm_name value is used to include the correct libraries for the resource manager automatically and properly to set up the interface between the transaction manager and resource manager (using the xa_switch_t structure).

-z

Specifies the __stdcall calling convention for the XA switch interfaces.

buildtms uses the buildserver command to produce the a.out. buildserver uses the CC and CFLAGS environment variables, if set, for the compiler and compiler flags, respectively.

buildtms is supported as an Oracle Tuxedo system-supplied compilation tool on any platform on which the Oracle Tuxedo ATMI or CORBA server environment is supported. RM XA libraries are not supported on the Windows platform.

buildtms -o $TUXDIR/bin/TMS_XYZ -r XYZ/SQL # TMS for XYZ resource manager

buildwsh—Builds customized workstation handler process.

buildwsh [ -v ] [ -o name ] [ -f files ]

buildwsh is used to construct a customized Oracle Tuxedo ATMI workstation handler module. The files included by the caller must include only the application buffer type switch and any required supporting routines. The command combines the files supplied by the -f option with the standard Oracle Tuxedo ATMI libraries necessary to form a workstation handler load module. The load module is built by the cc(1) command described in UNIX system reference manuals, which buildwsh invokes. The options to buildwsh have the following meaning:

-v

Specifies that buildwsh must work in verbose mode. In particular, it writes the cc command to its standard output.

-o name

Specifies the filename of the output workstation handler load module. The name specified here must also be specified with the -w WSHname option of the WSL(5) server in the SERVER section of the configuration file. If not supplied, the load module is named WSH.

-f firstfiles

Specifies one or more user files to be included in the compilation and/or link edit phases of buildwsh. Source files are compiled using the either the cc command or the compilation command specified through the CC environment variable. Object files resulting from compilation of source files and object files specified directly as arguments to the -f option are included after all object files necessary to build a base workstation handler process and before the Oracle Tuxedo ATMI libraries. If more than one file is specified, filenames must be separated by white space and the entire list must be enclosed in quotation marks. This option can be specified multiple times.

buildwsh normally uses the cc command to produce the a.out. In order to allow for the specification of an alternate compiler, buildwsh checks for the existence of a shell variable named CC. If CC does not exist in buildwsh’s environment, or if it is the string "", buildwsh will use cc as the compiler. If CC does exist in the environment, its value is taken to be the name of the compiler to be executed. Likewise, the shell variable CFLAGS is taken to contain a set of parameters to be passed to the compiler.

If your application uses shared libraries, it is not necessary to go through this compile and link process. See “Managing Typed Buffers” in Programming an Oracle Tuxedo ATMI Application Using C.

The buildwsh compilation tool is supported on any platform on which the Oracle Tuxedo ATMI server environment is supported.

CC=ncc CFLAGS=”-I $TUXDIR/include”; export CC CFLAGS buildwsh
-o APPWSH -f apptypsw.o

cobcc—COBOL compilation interface.

cobcc [option . . . ] filename . . .

cobcc is used as an interface shell to the COBOL compiler. It is invoked, by default, when buildclient(1) or buildserver(1) is executed with the -C (COBOL) option. This can be overridden by specifying the ALTCC environment variable.

The following list indicates the options recognized by cobcc. To use these options, set the environment variable ALTCFLAGS to the string of options to be recognized by cobcc when running buildclient or buildserver. Consult your documentation for the COBOL and C compilers to see what effect the various options have.

-c

This option specifies that the link phase must be suppressed. That is, compilation will be done but an executable program will not be generated.

-p -g -r -O

These options are passed directly to the COBOL compiler.

-l argument

This option and its argument are passed directly to the COBOL compiler (with no white space separating them).

-L argument

This option and its argument are passed directly to the COBOL compiler (with one space separating them).

-o output_file

This option is used to specify the name of the executable file that is output from the link stage.

-E -P -S

These options are passed through the COBOL compiler to the C compiler, and also cause suppression of the link phase.

-A -C -H -f -G

These options are passed through the COBOL compiler to the C compiler.

-w

This option causes warnings to be suppressed from both the COBOL and C compilers.

-D argument

This option and its argument are passed through the COBOL compiler to the C compiler. It is used to define macros in C.

{-T -Y -U -I -B -X -F -q} argument

Each of these options takes an argument. The option and its argument are passed through the COBOL compiler to the C compiler.

-V -v

Each of these options is passed both to the COBOL compiler and the C compiler.

-a -s

Each of these options is passed to the loader.

-u argument

This option and its argument are passed to the loader.

-W argument

The argument may consist of up to three comma-separated fields. If the first part of the argument is -p or -0, it is passed to the C compiler. If it starts with -a, it is passed to the assembler. If it starts with -l, it is passed to the loader. If it starts with -C, it is passed to the COBOL compiler. Otherwise, it is passed through to the C compiler.

The options and their arguments and the filenames are passed to the COBOL compiler with the correct options so that the right information is processed by the COBOL compiler, the C compiler, or the loader. The COBOL compiler name is assumed to be cob and already in the PATH.

cpy2record—Generates Oracle Tuxedo RECORD description file from copybook file.

cpy2record [OPTION...] FILE

This utility parses the COBOL copybook file and generates the corresponding Oracle Tuxedo RECORD description files. This tool is only used to parse COBOL copybook programs and will not parse files containing COBOL source statements.

cpy2record supports the following options:

-b

Specifies the base number for FML32 table. The default is 10000.

-i

With -i option, if #vname is not specified in copybook file, rname is not converted to lowcase as the default vname; without -i option, rname is converted to lowercase.

-R

Indicates this tool creates copybook description file.

-t

Specifies the generated FML32 table file; the followed parameter is the output FML32 table file name.

-o

Specifies the output file name, followed parameter is the output file name. If this parameter is not specified, the output file name changes the suffix of the input file name to .R. For example, abc.cbl is converted to abc.R.

PATH

Before using cpy2record, add TUXDIR/bin and Java command java to system environment PATH.

• The following example converts copybook file abc.cbl to RECORD file abc.R:

  • cpy2record /home/abc.cbl

    Or

  • cpy2record -R /home/abc.cbl
• The following example converts copybook file abc.cbl and outputs to view file xyz.R:
  • cpy2record -o xyz.R /home/abc.cbl
• The following example is a COBOL copybook file example.

  * customer.cpy
            01     CUSTOMER.
                05    name         PIC X(10).
                05    balance      PIC S9(9) COMP-5.
                05    address      PIC X(80).

dmadmin—Oracle Tuxedo Domains Administration Command Interpreter.

dmadmin [ -c ] [-2] [-s] [-e]

dmadmin is an interactive command interpreter used for the administration of domain gateway groups defined for a particular Oracle Tuxedo application involved in a Domains configuration. This page describes the use of dmadmin for TDomain gateways, SNA Gateways (SNAX), and OSI TP gateways of the Oracle Tuxedo Domains component. For a description of the Oracle Tuxedo Domains component, see Using the Oracle Tuxedo Domains Component.

dmadmin can operate in two modes: administration mode and configuration mode.

dmadmin enters administration mode when called with no parameters. Administration mode is the default mode. In this mode, dmadmin can be run on any active node (excluding workstations) within an active application. Application administrators can use this mode to obtain or change parameters on any active domain gateway group. Application administrators may also use this mode to create, destroy, or re-initialize the Domains transaction log for a particular local domain access point. In this case, the domain gateway group associated with that local domain access point must not be active, and dmadmin must be run on the machine assigned to the corresponding gateway group.

dmadmin requires the use of the Domains administrative server (DMADM) for the administration of the BDMCONFIG file, and the gateway administrative server (GWADM) for the reconfiguration of active domain gateway groups. There is one DMADM process running for each Oracle Tuxedo application involved in a Domains configuration, and there is one GWADM process running for each domain gateway group.

-c

dmadmin enters configuration mode when it is invoked with the -c option or when the config subcommand is invoked. Application administrators can use this mode to update or add new configuration information to the binary version of the Domains configuration file (BDMCONFIG).

-2

Specifies whether to add, update, or delete a second password pair (password pair 2). If not specified, the deault is password pair 1.

-s <start-time>

Specifies when a password pair becomes effective. If not specified,the password becomes effective immediately. Time must be specified in UTC string format (yyyy/mm/dd/hh:mm:ss).

-e <end-time>

Specifies when a password pair expires. If not specified, the password pair will not expires until it is deleted or updated explicitly from the system. Time must be specified in UTC string format (yyyy/mm/dd/hh:mm:ss).

Once dmadmin has been invoked, commands may be entered at the prompt (“>”) according to the following syntax:

command [arguments]

Several commonly occurring arguments can be given defaults via the default command. Commands that accept parameters set via the default command check default to see if a value has been set. If one has not been set, an error message is returned.

Once set, a default remains in effect until the session is ended, unless changed by another default command. Defaults may be overridden by entering an explicit value on the command line, or unset by entering an * (asterisk) value. The effect of an override lasts for a single instance of the command.

Output from dmadmin commands is paginated according to the pagination command in use (see the paginate subcommand in the discussion that follows).

The following commands are available in administration mode:

advertise (adv) -d local_domain_access_point_name [{service}]

Advertises all remote services provided by the named local domain access point or the specified remote service. If the local domain specified by -d option works on bypass-domain model, advertise only advertises those services that are exported by connected non-bypass remote domains. If a service name is given and the service locates in a remote domain which works on bypass-domain model or has not been connected yet, advertise raises an error.

advertiseevent (advevt) -d local_domain_name_[{-all | event}]

Allows all configured events (-all) or a specified event (named event) to be sent out to remote domains. These events are configured with LACCESSPOINT=local_domain_name in “*DM_EVT_OUT" section.

audit (audit) -d local_domain_access_point_name [{off | on}]

Activates (on) or deactivates (off) the audit trace for the named local domain access point. If no option is set, the current setting is toggled between the values on and off, and the new setting is printed. The initial setting is off.

When a multi-domain transaction is created in Oracle Tuxedo 8.0 or later software, the Domains transaction auditing feature will automatically write the global transaction ID (GTRID) from the remote (parent) application into the audit log of the local (subordinate) application, along with the local GTRID.

The audit record contains colon-delimited string fields in the following order: process ID, local domain access point name, remote domain access point name, service name, local GTRID (only in transaction mode), parent GTRID (only in transaction mode), audit record type (string), and current timestamp.

chbktime (chbt) -d local_domain_access_point_name-tbktime

Changes the blocking timeout for a particular local domain access point.

config (config)

Enters configuration mode. Commands issued in this mode follow the conventions defined in Configuration Mode Commands.

connect (co) -d local_domain_access_point_name [-R remote_domain_access_point_name]

Connects the local domain gateway to the remote domain gateway. If the connection attempt fails and you have configured the local domain gateway to retry a connection, repeated attempts to connect (via automatic connection retry processing) are made. (If -R is not specified, the command applies to all remote domain access points configured for this local domain gateway.)

crdmlog (crdlog)[-d local_domain_access_point_name]

Creates the Domains transaction log for the named local domain access point on the current machine (the machine where dmadmin is running). The command uses the parameters specified in the DMCONFIG file. This command fails if the domain gateway group associated with the named local domain access point is active on the current machine or if the log already exists.

Note:

When DMCONFIG(5) DMTLOGDEV is set to export tlog info to Oracle database, DMTLOG is no longer automatically created.

default (d) [-d local_domain_access_point_name]

Sets the corresponding argument to be the default local domain access point. Defaults may be unset by specifying * (asterisk) as an argument. If the default command is entered with no arguments, the current defaults are printed.

disconnect (dco) -d local_domain_access_point_name [-R remote_domain_access_point_name]

Breaks the connection between the local domain gateway and the remote domain gateway and does not initiate connection retry processing. If no connection is active, but automatic connection retry processing is in effect, this command stops the automatic retry processing. (If -R is not specified, the command applies to all remote domain access points configured for this local domain gateway.)

dsdmlog (dsdlg) -d local_domain_access_point_name [ -y]

Destroys the Domains transaction log for the named local domain access point on the current machine (that is, the machine where dmadmin is running). An error is returned if a Domains transaction log is not defined for this local domain access point, if the domain gateway group associated with the local domain access point is active, or if outstanding transaction records exist in the log. The term outstanding transactions means that a global transaction has been committed but an end-of-transaction has not yet been written. This command prompts for confirmation before proceeding unless the -y option is specified.

echo (e) [{off | on}]

Echoes input command lines when set to on. If no option is given, the current setting is toggled, and the new setting is printed. The initial setting is off.

forgettrans (ft) -d local_domain_access_point_name [ -t tran_id]

Forgets one or all heuristic log records for the named local domain access point. If the transaction identifier tran_id is specified, only the heuristic log record for that transaction is forgotten. The transaction identifier tran_id can be obtained from the printtrans command or from the ULOG file.

help (h) [command]

Prints help messages. If command is specified, the abbreviation, arguments, and description for that command are printed. Omitting all arguments causes the syntax of all commands to be displayed.

indmlog (indlg) -d local_domain_access_point_name [ -y]

Reinitializes the Domains transaction log for the named local domain access point on the current machine (that is, the machine where dmadmin is running). An error is returned if a DMTLOG is not defined for this local domain access point, if the domain gateway group associated with the local domain access point is active, or if outstanding transaction records exist in the log. The term outstanding transactions means that a global transaction has been committed but an end-of-transaction has not yet been written. The command prompts for confirmation before proceeding unless the -y option is specified.

paginate (page) [{off | on}]

Paginates output. If no option is given, the current setting is toggled, and the new setting is printed. The initial setting is on, unless either standard input or standard output is a non-tty device. Pagination may only be turned on when both standard input and standard output are tty devices. The shell environment variable PAGER may be used to override the default command used for paging output. The default paging command is the indigenous one to the native operating system environment, for example, the command pg is the default on UNIX system operating environments.

passwd (passwd) [ -r ] local_domain_access_point_name remote_domain_access_point_name [ LDOM RDOM |-2 | –s <start-time> -e <end-time>]

Prompts the administrator for new passwords for the specified local and remote domain access points. The -r option specifies that existing passwords and new passwords must be encrypted using a new key generated by the system. The password is limited to at most 30 characters. passwd is only supported by TDomain gateways.

LDOM RDOM

Adds password pair 1 for the TDOMAIN session <LDOM, RDOM>. The password becomes valid immediately, and never expires. If an old password pair 1 exists, this command fails.

LDOM RDOM -2

Adds password pair 2 for the TDOMAIN session <LDOM, RDOM>. The password becomes valid immediately, and never expires. If an old password pair 1 exists, this command fail.

LDOM RDOM –s <start-time> -e <end-time>

Adds password pair 1 (or password pair 2 if -2 is included) for the TDOMAIN session <LDOM, RDOM>. The password becomes valid at <start-time>, and expires at <end-time>. If an old password pair 1 exists, this command fails.

printdomain (pd) -d local_domain_access_point_name

Prints information about the named local domain access point. Information printed includes a list of connected remote domains, a list of remote domains being retried (if any), global information shared by the gateway group processes, and additional information that is dependent on the domain gateway type instantiation.

printstats (pstats) -d local_domain_access_point_name

Prints statistical and performance information gathered by the named local domain access point. The information printed is dependent on the domain gateway type.

printtrans (pt) -d local_domain_access_point_name

Prints transaction information for the named local domain access point. The output for each transaction record contains the following colon-delimited string fields:

process ID:local domain access point name:remote domain access point name:service name:local GTRID:remote GTRID:record type:timestamp

If the transaction is local to the domain, the remote GTRID field will be empty between the colon delimiters.

quit (q)

Terminates the session.

resume (res) -d local_domain_access_point_name [{ -all | service}]

Resumes processing of either the specified service or all remote services handled by the named local domain access point.

stats (stats) -d local_domain_access_point_name [{ off | on | reset }]

Activates (on), deactivates (off), or resets (reset) statistics gathering for the named local domain access point. If no option is given, the current setting is toggled between the values on and off, and the new setting is printed. The initial setting is off.

statsvc (statsvc) -d local_domain_access_point_name -t interval_time_number

Activates (on) or deactivates (off) the statistics audit trace for the named local domain access point with remote service call. If the interval time number is greater than 0, this feature is activated; the current interval time setting takes effect, and the initial setting is switched off. When you activate (on) the statistics audit trace, if no event occurs in the interval time, GWADM does not flush the data to audit file, meaning, GWADM only flushes the new data that occurs in an interval time to audit log file.

suspend (susp) -d local_domain_access_point_name [{ -all | service}]

Suspends one or all remote services for the named local domain access point.

topendpasswd (tepasswd) [ -r]

Prompts the administrator for a new password for the specified TOP END domain. The -r option specifies that the existing passwords and new password must be encrypted using a new key generated by the system.

unadvertise (unadv) -d local_domain_access_point_name [{service}]

Unadvertises one or all remote services for the named local domain access point. If the local domain specified by -d option works on bypass domain model, unadvertise only unadvertises those services that are exported by non-bypass remote domain. If a service name is given and the service locates in a remote domain which works on bypass domain model, advertise raises an error.

unadvertiseevent (unadvevt) -d local_domain_name_[{-all | event}]

Forbids all configured events (-all) or a specified event (named event) to be sent out to remote domains. These events are configured with LACCESSPOINT =local_domain_name in “*DM_EVT_OUT” section.

verbose (v) [{off | on}]

Produces output in verbose mode. If no option is given, the current setting is toggled, and the new setting is printed. The initial setting is off.

! shellcommand

Escapes to shell and executes shellcommand .

!!

Repeats previous shell command.

# [text]

Lines beginning with "#" are comment lines and are ignored.

<CR>

Repeats the last command.

The dmadmin command enters configuration mode when executed with the -c option or when the config subcommand is used. In this mode, dmadmin allows run-time updates to the BDMCONFIG file. dmadmin manages a buffer that contains input field values to be added or retrieved, and displays output field values and status after each operation completes. The user can update the input buffer using any available text editor.

dmadmin first prompts for the desired section followed by a prompt for the desired operation.

The prompt for the section of the BDMCONFIG file is as follows:

Section:
         1) RESOURCES                 2) LOCAL_DOMAINS
         3) REMOTE_DOMAINS            4) LOCAL_SERVICES
         5) REMOTE_SERVICES           6) ROUTING
         7) ACCESS_CONTROL            8) PASSWORDS
         9) TDOMAINS                  10) OSITPS
         11) SNADOMS                  12) LOCAL_REMOTE_USER
         13) REMOTE_USERS             14) SNACRMS
         15) SNASTACKS                16) SNALINKS
         19) OSITPX
         20) EVENTS_IN                21) EVENTS_OUT
         q) QUIT
Enter Section [1]:

The number of the default section appears in square brackets at the end of the prompt. You can accept the default by pressing RETURN or ENTER. To select another section enter its number, then press RETURN or ENTER.

dmadmin then prompts for the desired operation.

Operations:
         1) FIRST                 2) NEXT
         3) RETRIEVE              4) ADD
         5) UPDATE                6) DELETE
         7) NEW_SECTION           8) QUIT
Enter Operation [1]:

The number of the default operation is printed in square brackets at the end of the prompt. Pressing RETURN or ENTER selects this option. To select another operation enter its number, then press RETURN or ENTER.

The currently supported operations are:

1. FIRST—retrieves the first record from the specified section. No key fields are needed (they are ignored if in the input buffer).
2. NEXT—retrieves the next record from the specified section, based on the key fields in the input buffer.
3. RETRIEVE—retrieves the indicated record from the specified section by key field(s) (see fields description below).
4. ADD—adds the indicated record in the specified section. Any fields not specified (unless required) take their defaults as specified in DMCONFIG(5). The current value for all fields is returned in the output buffer. This operation can only be done by the Oracle Tuxedo administrator.
5. UPDATE—updates the record specified in the input buffer in the selected section. Any fields not specified in the input buffer remain unchanged. The current value for all fields is returned in the input buffer. This operation can only be done by the Oracle Tuxedo administrator.
6. DELETE—deletes the record specified in the input buffer from the selected section. This operation can only be done by the Oracle Tuxedo system administrator.
7. NEW SECTION—clears the input buffer (all fields are deleted). After this operation, dmadmin immediately prompts for the section again.
8. QUIT—exits the program gracefully (dmadmin is terminated). A value of q for any prompt also exits the program.

For configuration operations, the effective user identifier must match the Oracle Tuxedo administrator user identifier (UID) for the machine on which this program is executed. When a record is updated or added, all defaults and validations used by dmloadcf(1) are enforced.

dmadmin then prompts you to indicate whether you want to edit the input buffer:

Enter editor to add/modify fields [n]?

Entering a value of y puts the input buffer into a temporary file and executes the text editor. The environment variable EDITOR is used to determine which editor is to be used; the default is ed, a UNIX text editor. The input format is a set of field name/field value pairs and is described in the Configuration Input Format. The field names associated with each DMCONFIG section are listed in tables in the subsections that follow. The semantics of the fields and associated ranges, defaults, restrictions, and so on are described in DMCONFIG(5), and DM_MIB(5). In many cases, the field name is the same as the KEYWORD in the DMCONFIG file, prefixed with "TA_". When the user completes editing the input buffer, dmadmin reads it. If more than one line is included for a particular field name, the first line is used and other lines are ignored. If any errors occur, a syntax error is printed and dmadmin prompts you to indicate whether you want to edit the file to correct the problem:

Enter editor to correct? 

If the problem is not corrected (response n), the input buffer will contain no fields. Otherwise, the editor is executed again.

Finally, dmadmin asks whether the operation must be executed:

Perform operation [y]?

When the operation completes, dmadmin prints the return value as in Return value TAOK followed by the output buffer fields. The process then begins again with a prompt for the section. All output buffer fields are available in the input buffer unless the buffer is cleared.

Entering break at any time restarts the interaction at the prompt for the section.

When "QUIT" is selected, dmadmin prompts for authorization to create a backup text version of the configuration file:

Unload BDMCONFIG file into ASCII backup [y]?

If a backup is selected, dmadmin prompts for a filename:

Backup filename [DMCONFIG]

On success, dmadmin indicates that a backup was created; otherwise, an error is printed.

Input packets consist of lines formatted as follows:

fldname fldval

The field name is separated from the field value by one or more tabs (or spaces).

Lengthy field values can be continued on the next line by having the continuation line begin with one or more tabs (which are dropped when read back into dmadmin).

Empty lines consisting of a single newline character are ignored.

To enter an unprintable character in the field value or to start a field value with a tab, use a backslash followed by the two-character hexadecimal representation of the desired character (see ASCII(5) in a UNIX reference manual). A space, for example, can be entered in the input data as \20. A backslash can be entered using two backslash characters. dmadmin recognizes all input in this format, but its greatest usefulness is for non-printing characters.

The following are general limitations of the dynamic Domains reconfiguration capability:

• Values for key fields (as indicated in the following sections) may not be modified. Key fields can be modified, when the system is down, by reloading the configuration file.
• Dynamic deletions cannot be applied when the domain gateway group associated with a local domain access point is active (running).

For Oracle Tuxedo release 7.1 or later, the Domains MIB uses improved class and attribute terminology to describe the interaction between local and remote domains. The improved terminology has been applied to the DM_MIB reference page, classes, and error messages, and to the DMCONFIG reference page, section names, parameter names, and error messages. Although the improved terminology has not been applied to the dmadmin user interface, dmadmin understands both the previous and the improved DMCONFIG terminology.

For backwards compatibility, aliases are provided between the DMCONFIG terminology used prior to Oracle Tuxedo 7.1 and the improved Domains MIB terminology. In Oracle Tuxedo release 7.1 or later, dmadmin accepts both versions of the DMCONFIG terminology. For details, see Domains Terminology Improvements” in the DM_MIB(5) reference page.

The following sections describe, for each DMCONFIG section, the field identifiers associated with each DMCONFIG field, the field type of each identifier, and when each field can be updated. All applicable field values are returned with the retrieval operations. Fields that are allowed and/or required for adding a record are described in DMCONFIG(5), and DM_MIB(5). Fields indicated below as key are key fields that are used to uniquely identify a record within section. These key fields are required to be in the input buffer when updates are done and are not allowed to be updated dynamically. The Update column indicates when a field can be updated. The possible values are:

• Yes—can be updated at any time.
• NoGW—cannot be updated dynamically while the domain gateway group associated with the local domain access point is running.
• No—cannot be updated dynamically while at least one domain gateway group is running.

The following table lists the fields in the DM_LOCAL section (also known as the DM_LOCAL_DOMAINS section). At the dmadmin operation prompt, enter 2 (LOCAL_DOMAINS) to access this section.

{ON_DEMAND | ON_STARTUP |
                     INCOMING_ONLY}

{NONE | APP_PW | DM_PW}

The following table lists the fields in the DM_REMOTE section (also known as the DM_REMOTE_DOMAINS section). At the dmadmin operation prompt, enter 3 (REMOTE_DOMAINS) to access this section.

The DM_TDOMAIN section contains the network addressing parameters required by TDOMAIN type domains. The following table lists the fields in this section.

{LOCAL | ON_DEMAND | ON_STARTUP | INCOMING_ONLY}

For a local domain access point identifier (TA_LDOM), the TA_NWADDR and TA_NWDEVICE fields can be updated if the gateway group associated with that local domain access point is not running.

The DM_OSITP section contains the network addressing parameters for OSI TP 1.3 required by OSITP type domains. The following table lists the fields in this section.

For a local domain access point identifier (TA_LDOM), the other fields in this table can be updated if the gateway group associated with that local domain access point is not running.

The DM_OSITPX section contains the network addressing parameters for OSI TP 4.0 or later required by OSITPX type domains. The following table lists the fields in this section.

For a local domain access point identifier (TA_LDOM), the other fields in this table can be updated if the gateway group associated with that local domain access point is not running.

The following table lists the fields in the DM_EXPORT section (also known as the DM_LOCAL_SERVICES section). At the dmadmin operation prompt, enter 4 (LOCAL_SERVICES) to access this section.

The following table lists the fields in the DM_IMPORT section (also known as the DM_REMOTE_SERVICES section). At the dmadmin operation prompt, enter 5 (REMOTE_SERVICES) to access this section.

The following table lists the fields in the DM_EVT_IN section.

The following table lists the fields in the DM_EVT_OUT Section.

The following table lists the fields in the DM_ROUTING section.

The following table lists the fields in the DM_ACCESS_CONTROL section.

The following table lists the fields in the DM_PASSWORDS section. This section only applies to TDomain gateways.

The TA_LPWD and TA_RPWD show the existence of a defined password for the local and/or the remote domain access point. Passwords are not displayed. If an UPDATE operation is selected, the value of the corresponding field must be set to U. The program will then prompt with echo turned off for the corresponding passwords.

dmadmin fails if it cannot allocate an FML typed buffer, if it cannot determine the /etc/passwd entry for the user, or if it cannot reset the environment variables FIELDTBLS or FLDTBLDIR.

The return value printed by dmadmin after each operation completes indicates the status of the requested operation. There are three classes of return values.

The following return values indicate a problem with permissions or an Oracle Tuxedo communications error. They indicate that the operation did not complete successfully.

[TAEPERM]

The calling process specified an ADD, UPDATE, or DELETE operation but it is not running as the Oracle Tuxedo administrator. Update operations must be run by the administrator (that is, the user specified in the UID attribute of the RESOURCES section of the TUXCONFIG file).

[TAESYSTEM]

An Oracle Tuxedo error has occurred. The exact nature of the error is written to userlog(3c).

[TAEOS]

An operating system error has occurred.

[TAETIME]

A blocking timeout occurred. The input buffer was not updated so no information was returned for retrieval operations. The status of update operations can be checked by doing a retrieval on the record that was being updated.

The following return values indicate a problem in doing the operation itself and generally are semantic problems with the application data in the input buffer. The string field TA_STATUS will be set in the output buffer and will contain short text describing the problem. The string field TA_BADFLDNAME will be set to the field name for the field containing the value that caused the problem (assuming the error can be attributed to a single field).

[TAECONFIG]

An error occurred while the BDMCONFIG file was being read.

[TAEDUPLICATE]

The operation attempted to add a duplicate record.

[TAEINCONSIS]

A field value or set of field values are inconsistently specified.

[TAENOTFOUND]

The record specified for the operation was not found.

[TAENOSPACE]

The operation attempted to do an update but there was not enough space in the BDMCONFIG file.

[TAERANGE]

A field value is out of range or is invalid.

[TAEREQUIRED]

A field value is required but not present.

[TAESIZE]

A field value for a string field is too long.

[TAEUPDATE]

The operation attempted to do an update that is not allowed.

The following return values indicate that the operation was successful.

[TAOK]

The operation succeeded. No updates were made to the BDMCONFIG file.

[TAUPDATED]

The operation succeeded. Updates were made to the BDMCONFIG file.

When using dmunloadcf to print entries in the configuration, optional field values are not printed if they are not set (for strings) or 0 (for integers). These fields will always appear in the output buffer when using dmadmin. In this way, it makes it easier for the administrator to retrieve an entry and update a field that previously was not set. The entry will have the field name followed by a tab but no field value.

In the following example, dmadmin is used to add a new remote domain access point. For illustration purposes, ed(1) is used for the editor.

$ EDITOR=ed dmadmin
> config
Sections:
         1) RESOURCES           2) LOCAL_DOMAINS
         3) REMOTE_DOMAINS      4) LOCAL_SERVICES
         5) REMOTE_SERVICES     6) ROUTING
         7) ACCESS_CONTROL      8) PASSWORDS
         9) TDOMAINS            10) OSITPS
         11) SNADOMS            12) LOCAL_REMOTE_USER
         13) REMOTE_USERS       14) SNACRMS
         15) SNASTACKS          16) SNALINKS
         19) OSITPX
         q) QUIT
Enter Section [1]:
Enter Section [1]: 2
Operations:
         1) FIRST           2) NEXT
         3) RETRIEVE        4) ADD
         5) UPDATE          6) DELETE
         7) NEW_SECTION     8) QUIT
Enter Operation [1]: 4
Enter editor to add/modify fields [n]? y
a
TA_RDOM         B05
TA_DOMAINID     BA.BANK05
TA_TYPE         TDOMAIN
.
w
53
q
Perform operation [y]? <return>
Return value TAUPDATED
Buffer contents:
TA_OPERATION           4
TA_SECTION             2
TA_DOMAINID            BA.BANK05
TA_RDOM B05
TA_TYPE TDOMAIN
TA_STATUS              Update completed successfully
Operations:
         1) FIRST           2) NEXT
         3) RETRIEVE        4) ADD
         5) UPDATE          6) DELETE
         7) NEW_SECTION     8) QUIT
Enter Operation [4]: 7
Section:
         1) RESOURCES           2) LOCAL_DOMAINS
         3) REMOTE_DOMAINS      4) LOCAL_SERVICES
         5) REMOTE_SERVICES     6) ROUTING
         7) ACCESS_CONTROL      8) PASSWORDS
         9) TDOMAINS            10) OSITPS
         11) SNADOMS            12) LOCAL_REMOTE_USER
         13) REMOTE_USERS       14) SNACRMS
         15) SNASTACKS          16) SNALINKS
         19) OSITPX
         q) QUIT
Enter Section [1]: 9
Operations:
         1) FIRST 2) NEXT
         3) RETRIEVE 4) ADD
         5) UPDATE 6) DELETE
         7) NEW_SECTION 8) QUIT
Enter Operation [6]: 4
Enter editor to add/modify fields [n]? y
a
TA_RDOM        B05
TA_NWADDR      0x00020401c0066d05
TA_NWDEVICE    /dev/tcp
.
w
55
q
Perform operation [y]? <return>
Return value TAUPDATED
Buffer contents:
TA_OPERATION         4
TA_SECTION           8
TA_RDOM              B05
TA_NWADDR            0x00020401c0066d05
TA_NWDEVICE          /dev/tcp
TA_STATUS            Update completed successfully
Operations:
         1) FIRST               2) NEXT
         3) RETRIEVE            4) ADD
         5) UPDATE              6) DELETE
         7) NEW_SECTION         8) QUIT
Enter Operation [4]: 8
> quit

The dmadmin program ends.

If dmadmin is run using the UID of the application administrator, it is assumed that the user is a trusted user and security is bypassed. If dmadmin is run with another user ID, and the security option is enabled in the TUXCONFIG file, the corresponding application password is required to start the dmadmin program. If standard input is a terminal, dmadmin will prompt the user for the password with echo turned off. If standard input is not a terminal, the password is retrieved from the environment variable, APP_PW. If this environment variable is not specified and an application password is required, dmadmin will fail to start.

When running with another user ID (other than the UID of the administrator) only a limited set of commands is available.

dmadmin resets the FIELDTBLS and FLDTBLDIR environment variables to pick up the ${TUXDIR}/udataobj/dmadmin field table. Hence, the TUXDIR environment variable must be set correctly.

If the application requires security and the standard input to dmadmin is not from a terminal, the APP_PW environment variable must be set to the corresponding application password.

The TUXCONFIG environment variable must be set to the pathname of the Oracle Tuxedo configuration file.

If the dmadmin command is entered before the system has been booted, the following message is displayed:

BBL and DMADM need to be booted before running dmadmin. Exiting...  

dmadmin then prompts for the corresponding commands.

If an incorrect application password is entered or is not available to a shell script through the environment, a log message is generated, the following message is displayed, and the command terminates:Invalid password entered.

dmadmin must be installed on Oracle Tuxedo release 5.0 or later. Other nodes in the same domain with a release 5.0 gateway may be Oracle Tuxedo release 4.1 or later.

The dmadmin administrative tool is supported on any platform on which the Oracle Tuxedo server environment is supported.

dmloadcf—Parses a DMCONFIG file and loads a binary BDMCONFIG configuration file.

dmloadcf [-c] [-n] [-y] [-b blocks] {DMCONFIG_file| - }

dmloadcf reads a file or standard input that is in DMCONFIG syntax, checks the syntax, and optionally loads a binary BDMCONFIG configuration file. The BDMCONFIG environment variable points to the pathname of the BDMCONFIG file where the information must be stored.

dmloadcf prints an error message if it finds any required section of the DMCONFIG file missing. If a syntax error is found while the input file is being parsed, dmloadcf exits without performing any updates to the BDMCONFIG file.

dmloadcf requires the existence of the $TUXDIR/udataobj/DMTYPE file. This file defines valid domain types. If this file does not exist, dmloadcf exits without performing any updates to the BDMCONFIG file.

The effective user identifier of the person running dmloadcf must match the UID in the RESOURCES section of the TUXCONFIG file.

The -c option to dmloadcf causes the program to print the minimum amount of IPC resources needed for each local domain (gateway group) in this configuration. The BDMCONFIG file is not updated.

The -n option to dmloadcf causes the program to do only syntax checking of the text DMCONFIG file without updating the BDMCONFIG file.

After syntax checking, dmloadcf checks whether the file referenced by the BDMCONFIG environment variable exists, is a valid Oracle Tuxedo file, and contains BDMCONFIG tables. If these conditions are not true, dmloadcf gives the user a chance to create and initialize the file by displaying the following prompt:

Initialize BDMCONFIG file:  path  [y,q]? 

Here path is the complete filename of the BDMCONFIG file. Prompting is suppressed if the standard input and output are not directed to a terminal, or if the -y option is specified on the command line. Any response other than “y” or “Y” causes dmloadcf to exit without creating a binary configuration file.

If the BDMCONFIG file is not properly initialized, and the user has entered y after the Initialize BDMCONFIG file prompt, dmloadcf creates the Oracle Tuxedo filesystem and creates the BDMCONFIG tables. If the -b option is specified on the command line, its argument defines the number of blocks for the device when the Oracle Tuxedo filesystem is created. If the value of the -b option is large enough to hold the new BDMCONFIG tables, dmloadcf uses the specified value to create the new filesystem; otherwise, dmloadcf prints an error message and exits. If the -b option is not specified, dmloadcf creates a new filesystem large enough to hold the BDMCONFIG tables. The -b option is ignored if the filesystem already exists. The -b option is highly recommended if BDMCONFIG is a raw device (that is, a device that has not been initialized). In this case, -b must be used to set the number of blocks on the raw device. The -b option is not recommended if BDMCONFIG is a regular UNIX file.

If the BDMCONFIG file has been initialized already, dmloadcf ensures that the local domain described by that BDMCONFIG file is not running. If a local domain is running, dmloadcf prints an error message and exits. Otherwise, dmloadcf, to confirm that the file must be overwritten, prompts the user with:

“Really overwrite BDMCONFIG file [y, q]?”

Prompting is suppressed if the standard input or output are not a terminal or if the -y option is specified on the command line. Any response other than “y” or “Y” will cause dmloadcf to exit without overwriting the file.

If the SECURITY parameter is specified in the RESOURCES section of the TUXCONFIG file, dmloadcf flushes the standard input, turns off terminal echo, and prompts the user for an application password as follows: Enter Application Password? The password is limited to 30 characters. The option to load the text DMCONFIG file via the standard input (rather than a file) cannot be used when this SECURITY parameter is turned on. If the standard input is not a terminal, that is, if the user cannot be prompted for a password (as with a here file, for example), the environment variable APP_PW is accessed to set the application password. If the environment variable APP_PW is not set with the standard input not a terminal, dmloadcf will print an error message, generate a log message and fail to load the BDMCONFIG file.

If no errors have occurred and all checks have passed, dmloadcf loads the DMCONFIG file into the BDMCONFIG file. It overwrites all existing information found in the BDMCONFIG tables.

For Oracle Tuxedo release 7.1 or later, the Domains MIB uses improved class and attribute terminology to describe the interaction between local and remote domains. The improved terminology has been applied to the DM_MIB reference page, classes, and error messages, and to the DMCONFIG reference page, section names, parameter names, and error messages. For details, see “Domains Terminology Improvements” in the DM_MIB(5) reference page.

For backwards compatibility, aliases are provided between the DMCONFIG terminology used prior to Oracle Tuxedo 7.1 and the improved Domains MIB terminology. In Oracle Tuxedo 7.1 or later, dmloadcf accepts both versions of the DMCONFIG terminology. By default, dmunloadcf generates a DMCONFIG file that uses the improved domains terminology. Use the -c option of dmunloadcf to generate a DMCONFIG file that uses the previous domains terminology.

The dmloadcf administrative tool is supported on any platform on which the Oracle Tuxedo server environment is supported.

The BDMCONFIG environment variable must point to the BDMCONFIG file.

The following example shows how a binary configuration file is loaded from the bank.dmconfig text file. The BDMCONFIG device is created (or reinitialized) with 2000 blocks:

dmloadcf -b 2000 bank.dmconfig

If an error is detected in the input, the offending line is printed to standard error, along with a message indicating the problem. If a syntax error is found in the DMCONFIG file or the system is currently running, no information is updated in the BDMCONFIG file and dmloadcf exits with exit code 1.

If dmloadcf is run on an active node, the following error message is displayed:

*** dmloadcf cannot run on an active node ***

If dmloadcf is run by a person whose effective user identifier does not match the UID specified in the TUXCONFIG file, the following error message is displayed:

*** UID is not effective user ID ***

Upon successful completion, dmloadcf exits with exit code 0. If the BDMCONFIG file is updated, a userlog message is generated to record this event.

dmunloadcf—Unloads the binary BDMCONFIG Domains configuration file.

dmunloadcf [-c]

dmunloadcf translates the BDMCONFIG configuration file from the binary representation into text. This translation is useful for transporting the file in a compact way between machines with different byte orderings, and for making a backup copy of the file in a compact form for reliability. The text format is the same as that described in DMCONFIG(5).

dmunloadcf reads values from the BDMCONFIG file referenced by the BDMCONFIG environment variable and writes them to standard output.

For Oracle Tuxedo release 7.1 or later, dmunloadcf, by default, generates a DMCONFIG file that uses the improved domains terminology. For details, see the following section, “Domains Terminology Improvements.” Use the -c option to generate a DMCONFIG file that uses the previous domains terminology.

For Oracle Tuxedo release 7.1 or later, the Domains MIB uses improved class and attribute terminology to describe the interaction between local and remote domains. The improved terminology has been applied to the DM_MIB reference page, classes, and error messages, and to the DMCONFIG reference page, section names, parameter names, and error messages. For details, see “Domains Terminology Improvements” in the DM_MIB(5) reference page.

For backward compatibility, aliases are provided between the DMCONFIG terminology used prior to Oracle Tuxedo 7.1 and the improved Domains MIB terminology. In Oracle Tuxedo 7.1 or later, dmloadcf accepts both versions of the DMCONFIG terminology. By default, dmunloadcf, generates a DMCONFIG file that uses the improved domains terminology. Use the -c option of dmunloadcf to generate a DMCONFIG file that uses the previous domains terminology.

The dmunloadcf command is supported on any platform on which the Oracle Tuxedo server environment is supported.

To unload the configuration in /usr/tuxedo/BDMCONFIG into the file bdmconfig.backup :

BDMCONFIG=/usr/tuxedo/BDMCONFIG dmunloadcf >bdmconfig.backup
          

dmunloadcf checks that the file referenced by the BDMCONFIG environment variable exists, is a valid Oracle Tuxedo filesystem, and contains BDMCONFIG tables. If any of these conditions is not met, dmunloadcf prints an error message and exits with error code 1. Upon successful completion, dmunloadcf exits with exit code 0.

gencat—Generates a formatted message catalog.

gencat [-m] catfile msgfile . . .

The gencat utility merges the message text source file(s) msgfile into a formatted message database catfile . The database catfile is created if it does not already exist. If catfile does exist its messages are included in the new catfile . If set and message numbers collide, the new message text defined in msgfile replaces the old message text currently contained in catfile . The message text source file (or set of files) input to gencat can contain either set and message numbers or simply message numbers, in which case the set NL_SETD (see nl_types(5)) is assumed.

$set n comment

Where n specifies the set identifier of the following messages until the next $set, $delset, or end-of-file appears. n must be a number in the range (1-{NL_SETMAX}). Set identifiers within a single source file need not be contiguous. Any string following the set identifier is treated as a comment. If no $set directive is specified in a message text source file, all messages are located in the default message set. NL_SETD.

$delset n comment

Deletes message set n from an existing message catalog. Any string following the set number is treated as a comment. (Note: if n is not a valid set it is ignored.)

$ comment

A line beginning with a dollar symbol ($) followed by an ASCII space or tab character is treated as a comment.

m message_text

The m denotes the message identifier, which is a number in the range (1-{NL_MSGMAX}). (Do not confuse this message text syntax with the -m command line option described under NOTES.) The message text is stored in the message catalog with the set identifier specified by the last $set directive, and with message identifier m . If the message text is empty, and an ASCII space or tab field separator is present, an empty string is stored in the message catalog. If a message source line has a message number, but neither a field separator nor message text, the existing message with that number (if any) is deleted from the catalog. Message identifiers need not be contiguous. The length of message text must be in the range (0-{NL_TEXTMAX}).

$quote c

This line specifies an optional quote character c , which can be used to surround message text so that trailing spaces or null (empty) messages are visible in a message source line. By default, or if an empty $quote directive is supplied, no quoting of message text is recognized. Empty lines in a message text source file are ignored. Text strings can contain the special characters and escape sequences defined in the following table.

The escape sequence \ddd consists of a backslash followed by 1, 2, or 3 octal digits, which are taken to specify the value of the desired character. If the character following a backslash is not one of those specified, the backslash is ignored.

A backslash followed by an ASCII newline character is also used to continue a string on the following line. Thus, the following two lines describe a single message string:

1 This line continues \ 
to the next line

which is equivalent to:

1 This line continues to the next line

gencat is supported on any platform on which the Oracle Tuxedo server environment is supported.

This version of gencat produces a catalog that at run time is read into malloc’ed space. Shared catalogs available with some versions of gencat are not available. On some systems, generation of malloc’ed catalogs requires that the -m option be specified. This option can be specified on the command line, but has no effect. malloc’ed catalogs are the default; the -m option is supported for compatibility only.

The catalog file generated by this command is limited in size to 64K. Larger catalog files result in an error being reported by this command and no catalog file being generated.

genicf—Generates an Implementation Configuration File (ICF).

genicf [options] idl-filename...

Given the idl-filename(s), generates an ICF file that provides the code generation process with additional information about policies on implementations and the relationship between implementations and the interface they implement. If an ICF file is provided as input to the idl command, the idl command generates server code for only the implementation/interface pairs specified in the ICF file.

The generated ICF file has the same filename as the first idl-filename specified on the command line, but with an .icf extension.

If incorrect OMG IDL syntax is specified in the idl-filename(s) file, appropriate errors are returned.

-D identifier=[definition]

Performs the same function as the #define C++ preprocessor directive; that is, the -D option defines a token string or a macro to be substituted for every occurrence of a given identifier in the definition file. If a definition is not specified, the identifier is defined as 1. Multiple -D options can be specified. White space between the -D option and the identifier is optional.

-I pathname

Specifies directories within which to search for include files, in addition to any directories specified with the #include OMG IDL preprocessor directive. Multiple directories can be specified by using multiple -I options.

There are two types of #include OMG IDL preprocessor directives: system (for example, <a.idl>) and user (for example, "a.idl"). On UNIX systems, the path for system #include directories is /usr/include and any directories specified with the -I option; the path for user #include directives is the location of the file containing the #include directive, followed by the path specified for the system #include directive. On Windows 2003 systems, no distinction is made between the system #include directories and the user #include directives.

-h and -?

Provides help that explains the usage of the genicf command. No other action results.

idl—Compiles the Object Management Group (OMG) Interface Definition Language (IDL) file and generates the files required for the interface.

idl [-i] [-D identifier [=value]] [-Ipathname][-h] [-P] [-T] 
idl-filename... [icf-filename...] 

Given the provided idl-filename() file(s) and optional icf-filename() file(s), the idl command generates the following files:

idl-filename _c.cpp

Client stub (includes embedded user-defined data type functions).

idl-filename _c.h

Class definitions for interfaces.

idl-filename _s.cpp

Server skeleton containing an implementation of the POA_skeleton classes.

idl-filename _s.h

POA_skeleton class definitions.

idl-filename _i.cpp

Example version of the implementation. This file is generated only when the -i option is given.

idl-filename _i.h

Class definition of an example implementation that inherits from the POA_skeleton class. This file is generated only when the -i option is given.

The IDL compiler places the generated client stub information in the filename_c.cpp and filename_c.h files. The generated server skeleton information is placed in the filename_s.cpp and filename_s.h files.

The IDL compiler overwrites the generated client stub files (filename_c.cpp and filename_c.h), and the generated server skeleton files (filename_s.cpp and filename_s.h). Any previous versions are destroyed.

When using the -i option, the IDL compiler overwrites the sample implementation class definition file (filename_i.h). Previous versions are destroyed. The sample implementation file (filename_i.cpp) is overwritten, however, any code contained within the code preservation blocks is preserved and restored in the newly generated file. To avoid the loss of data, it is recommended that you copy the sample implementation files (filename_i.h and filename_i.cpp) to a safe location before regenerating these files.

If an unknown option is passed to this command, the offending option and a usage message is displayed to the user, and the compile is not performed.

idl filename

The name of one or more files that contain OMG IDL statements.

-D identifier[=definition]

Performs the same function as the #define C++ preprocessor directive; that is, the -D option defines a token string or a macro to be substituted for every occurrence of a given identifier in the definition file. If a definition is not specified, the identifier is defined as

1. Multiple -D options can be specified. White space between the -D option and the name is optional.

-I pathname

Specifies directories within which to search for include files, in addition to any directories specified with the #include OMG IDL preprocessor directive. Multiple directories can be specified by using multiple -I options.

Specifies directories within which to search for include files, in addition to any directories specified with the #include OMG IDL preprocessor directive. Multiple directories can be specified by using multiple -I options.

There are two types of #include OMG IDL preprocessor directives: system (for example, <a.idl>) and user (for example, "a.idl"). The path for system #include directories is the system include directory and any directories specified with the -I option. The path for user #include directives is the location of the file containing the #include directive, followed by the path specified for the system #include directive.

By default, the text in files included with an #include directive is not included in the client and server code that is generated.

-i

Results in idl-filename_i.cpp files being generated. These files contain example templates for the implementations that implement the interfaces specified in the OMG IDL file.

Note:

When using the idl command -i option to update your implementation files, proceed as follows to update your implementation files:

1. Back up your implementation files.
2. If you are migrating from Oracle ObjectBroker to Oracle Tuxedo, edit your generated implementation files to change the code preservation block delimiters from “OBB_PRESERVE_BEGIN” and “OBB_PRESERVE_END” to “M3_PRESERVE_BEGIN” and “M3_PRESERVE_END”.
3. If you added include files to your method implementation file (*_i.cpp), edit the file and move the includes inside the INCLUDES preservation block.
4. Regenerate your edited implementation files (using the idl command with the -i option).
5. If you previously made modifications to the implementation definition file (*_i.h), edit the newly generated definition file and add your modifications back in. Be sure to put your modifications inside the code preservation blocks so subsequent updates will automatically retain them. Pay particular attention to the implementation constructor and destructor functions; the function signatures changed in Oracle Tuxedo release 7.1.
6. If you previously made modifications outside the preservation blocks of the method implementation file (*_i.cpp) or to the implementation constructor and destructor functions, edit the newly generated file and add those modifications. Be sure to put the modifications inside a preservation block so subsequent updates will automatically retain them.

-P

Generates server code that uses the POA instead of the TP Framework. With this option specified, the skeleton class does not inherit from the TP Framework Tobj_ServantBase class, but instead inherits directly from the PortableServer::ServantBase class. By default, the skeleton class uses the TP Framework. So you must use this switch when you are developing joint client/servers as these servers do not use the TP framework.

Not having the Tobj_ServantBase class in the inheritance tree for a servant means that the servant does not have activate_object and deactivate_object methods. In CORBA servers these methods are called by the TP Framework to dynamically initialize and save a servant's state before invoking a method on the servant. For CORBA joint client/servers, user-written code must explicitly create a servant and initialize a servant's state; therefore, the Tobj_ServantBase operations are not needed. When using the -P option, ICF files are not used because the TP Framework is not available.

-T

Generates tie-based servant code that allows the use of delegation to tie an instance of a C++ implementation class to the servant. This option allows classes that are not related to skeletons by inheritance to implement CORBA object operations. This option is set to off by default.

-h or -?

Provides help that explains the usage of the idl command. No other action results.

idl emp.idl
idl emp.idl emp.icf

idl2ir—Creates the Interface Repository and loads interface definitions into it.

idl2ir [options] definition-filename-list

The options are as follows:

[-f repository-name] [-c]
[-D identifier[=definition]]
[-I pathname[-I pathname] [...]] [-N{i|e}]

Use this command to create the Interface Repository and to load it with interface definitions. If no repository file exists, this command creates it. If a repository file does exist, this command loads the specified interface definitions into it and, in effect, updates the file.

One of the side effects of doing this is that a new Interface Repository database file is created.

definition-filename-list

A list of file specifications containing the repository definitions. These files are treated as one logical file and are loaded in one operation.

-f repository-name

The filename of the Interface Repository file. If you do not specify the-f option, the idl2ir command creates repository.ifr as the Interface Repository file on UNIX systems and repository_1.ifr on Microsoft Windows 2003 systems.

-c

Indicates that a new repository is to be created. If a repository exists and this option is specified, the idl2ir command ignores the existing repository and replaces it with a new one. If a repository exists and this option is not specified, the idl2ir command updates the existing repository.

-D identifier[=definition]

Performs the same function as the #define preprocessor directive; that is, the -D option defines a token string or a macro to be substituted for every occurrence of a given identifier in the definition file. If a definition is not specified, the identifier is defined as 1.You can specify multiple -D options.

-I pathname

Specifies a directory within which to search for include files, in addition to any directories specified with the #include OMG IDL preprocessor directive.

There are two types of #include OMG IDL preprocessor directives: system (for example, <a.idl>) and user (for example, "a.idl"). The path for system #include directives is /usr/include for UNIX systems, and any directories specified with the -I option. The path for system #include directives is the local directory for Windows NT systems, and any directories specified with the -I option.

The path for user #include directives is the current directory and any directories specified with the -I option. Multiple -I options can be specified.

Shows the contents of an Interface Repository.

ir2idl [options] [ interface-name]

The options are as follows:

[-f repository-name] [-n]
[-t interface-type] [-o filename]

This command shows the contents of an Interface Repository. By directing the output to a file with the -o option, you can extract the OMG IDL file from the repository. By default, the repository file is repository.ifr.

interface-name

The name of the interface whose contents are to be shown. If you do not specify an interface name, all interfaces in the repository are shown.

-f repository-name

The name of the repository to search for the interface definitions. If you do not specify the -f option, repository.ifr is used.

-n

Specifies that the output must not include those objects that were inherited.

-t interface-type

Indicates the type of objects to display. The object type must be one of the following keywords:

Attribute

Constant

Exception

Interface

Method

Module

Operation

Typedef

If you do not specify this option, the default is to display all of the types.

-o filename

The file specification for the file in which to write the retrieved OMG IDL statements. The default is standard output.

Deletes the specified object from an Interface Repository.

irdel [-f repository-name] [-i id]object-name
          

This command deletes the specified interface from the repository. Only interfaces not referenced from another interface can be deleted. By default, the repository file is repository.ifr.

-f repository-name

An optional parameter that specifies an Interface Repository. The repository-name value is the file specification of an Interface Repository. If this option is not specified, the repository.ifr is used as the default.

-i id

The repository id for the specified object. The id is used as a secondary level of lookup. If the id does not match the id of the named object, the object is not deleted.

object-name

The name of the interface to delete from the repository. The name can be a simple object name or a scoped name, for example, MOD1::INTERF2::OP3 (operation OP3 is within interface INTERF2, which is in application MOD1).

mkfldcs, mkfldcs32—Creates C# header files from field tables

mkfldcs is similar to mkfldhdr except its output file is used to generate C# source files which contain public classes including the definitions for every FML field ID provided in the input files.

The mkfldcs command line options are the same as mkfldhdr, mkfldhdr32(1). mkfldcs32 is used for 32-bit FML.

mkfldhdr, mkfldhdr32—Creates header files from field tables.

mkfldhdr [-d outdir] [ field_table... ]
mkfldhdr32 [-d outdir] [ field_table... ]

mkfldhdr translates each field table file to a corresponding header file suitable for inclusion in C programs. The resulting header files provide #define macros for converting from field names to field IDs. Header filenames are formed by concatenating a .h to the simple filename for each file to be converted.

The field table names may be specified on the command line; each file is converted to a corresponding header file.

If the field table names are not given on the command line, the program uses the FIELDTBLS environment variable as the list of field tables to be converted, and FLDTBLDIR environment variable as a list of directories to be searched for the files. FIELDTBLS specifies a comma-separated list of field table filenames. If FIELDTBLS has no value, fld.tbl is used as the name of the (only) field table file (in this case, the resulting header file will be (fld.tbl.h).

The FLDTBLDIR environment variable is a colon-separated list of directories in which to look for each field table whose name is not an absolute pathname; the search for field tables is very similar to the search for executable commands using the UNIX system PATH variable. If FLDTBLDIR is not defined, only the current directory is searched. Thus, if no field table names are specified on the command line and FIELDTBLS and FLDTBLDIR are not set, mkfldhdr will convert the field table fld.tbl in the current directory into the header file fld.tbl.h.

mkfldhdr32 is used for 32-bit FML. It uses the FIELDTBLS32 and FLDTBLDIR32 environment variables.

-d

Specifies that the output header files are to be created in a directory other than the present working directory.

Error messages are printed if the field table load fails or if an output file cannot be created.

FLDTBLDIR=/project/fldtbls
FIELDTBLS=maskftbl,DBftbl,miscftbl,
export FLDTBLDIR FIELDTBLS

mkfldhdr produces the #include files maskftbl.h, DBftbl.h, and miscftbl.h in the current directory by processing the files maskftbl, DBftbl, and miscftbl in directory /project/fldtbls.

With environment variables set as in the example above, the command mkfldhdr -d $FLDTBLDIR processes the same input field-table files, and produces the same output files, but places them in the directory given by the value of the environment variable FLDTBLDIR.

The command mkfldhdr myfields processes the input file myfields and produces myfields.h in the current directory.

mklanginfo—Compiles language information constants for a locale.

mklanginfo [ fname ]

This program takes the file specified as an argument, and converts the input into a file suitable for placement in $TUXDIR/locale/xx/LANGINFO where xx is a specific locale. The standard input is used if a file argument is not specified. The language values are used by setlocale(3c), strftime(3c), and nl_langinfo(3c) in the Section 3c - C Functions .

mklanginfo reads input lines, ignoring lines that begin with white space or ‘#’. Value input lines must be of the form:

<token> = “value”

The characters between the token and the double-quoted value can be anything but a double quote as long as white space appears after the token. If 0value is the null string, the line is ignored. Otherwise, token must be either an integer between 1 and 48, inclusive, or a string, as follows:

Integer String Value 1

DAY_1     Day 1 of the week, for example, Sunday 2
DAY_2     Day 2 of the week, for example, Monday 3
DAY_3     Day 3 of the week, for example, Tuesday 4
DAY_4     Day 4 of the week, for example, Wednesday 5
DAY_5     Day 5 of the week, for example, Thursday 6
DAY_6     Day 6 of the week, for example, Friday 7
DAY_7     Day 7 of the week, for example, Saturday 8
ABDAY_1   Abbreviated day 1 of the week, for example, Sun 9
ABDAY_2   Abbreviated day 2 of the week, for example, Mon 10
ABDAY_3   Abbreviated day 3 of the week, for example, Tue 11
ABDAY_4   Abbreviated day 4 of the week, for example, Wed 12
ABDAY_5   Abbreviated day 5 of the week, for example, Thu 13
ABDAY_6   Abbreviated day 6 of the week, for example, Fri 14
ABDAY_7   Abbreviated day 7 of the week, for example, Sat 15
MON_1     Month 1 of the year, for example, January 16
MON_2     Month 2 of the year, for example, February 17
MON_3     Month 3 of the year, for example, March 18
MON_4     Month 4 of the year, for example, April 19
MON_5     Month 5 of the year, for example, May 20
MON_6     Month 6 of the year, for example, June 21
MON_7     Month 7 of the year, for example, July 22
MON_8     Month 8 of the year, for example, August 23
MON_9     Month 9 of the year, for example, September 24
MON_10    Month 10 of the year, for example, October 25
MON_11    Month 11 of the year, for example, November 26
MON_12    Month 12 of the year, for example, December 27
ABMON_1   Abbreviated month 1 of the year, for example, Jan 28
ABMON_2   Abbreviated month 2 of the year, for example, Feb 29
ABMON_3   Abbreviated month 3 of the year, for example, Mar 30
ABMON_4   Abbreviated month 4 of the year, for example, Apr 31
ABMON_5   Abbreviated month 5 of the year, for example, May 32
ABMON_6   Abbreviated month 6 of the year, for example, Jun 33
ABMON_7   Abbreviated month 7 of the year, for example, Jul 34
ABMON_8   Abbreviated month 8 of the year, for example, Aug 35
ABMON_9   Abbreviated month 9 of the year, for example, Sep 36
ABMON_10  Abbreviated month 10 of the year, for example, Oct 37
ABMON_11  Abbreviated month 11 of the year, for example, Nov 38
ABMON_12  Abbreviated month 12 of the year, for example, Dec 39
RADIXCHAR Radix character, for example, '.' 40
THOUSEP   Separator for thousands 41
YESSTR    Affirmative response string, for example, yes 42
NOSTR     Negative response string, for example, no 43
CRNCYSTR  Currency symbol 44
D_T_FMT   string for formatting date and time, for example, “%a%b%d%H:%M:0Y” 45
D_FMT     string for formatting date, for example, “%m/%d/%y” 46
T_FMT     string for formatting time, for example, “H:%M:%S” 47
AM_FMT    Ante Meridian affix, for example, AM 48
PM_FMT    Post Meridian affix, for example, PM

The input lines may appear in any order. If an input line appears more than once for the same value, the last line for that value is used.

After processing the file, mklanginfo prints the string name and string value for each language information constant shown in the previous code listing to the standard error in the order specified in the listing. The null string is used as a value for any language information constant not specified; nl_langinfo uses the default value for the C locale (U.S. English values) for these unset constants.

If a filename is specified on the command name, mklanginfo writes the compiled output to fname.out; otherwise, the output is written to the standard output. The format is a list of all of the null-terminated string values (without newlines).

If an error occurs in reading the file or in the syntax, an error message is printed to the standard error and the program exits with exit code 1. On success, the program exits with exit code 0.

The defaults for the Oracle Tuxedo system (locale C) are located in $TUXDIR/locale/C/lang.text. To provide French values, an administrator might do the following (on a UNIX system platform):

mkdir $TUXDIR/locale/french
cd $TUXDIR/locale/french
cp $TUXDIR/locale/C/lang.text .
ed lang.text

convert to French values

w
q
mklanginfo lang.text > LANGINFO

$TUXDIR/locale/C/lang.text—the default values for the C locale

$TUXDIR/locale/C/LANGINFO—the “compiled” file for the C locale

$TUXDIR/locale/xx/LANGINFO—the “compiled” file for the xx locale

The mklanginfo command and the resulting LANGINFO file are needed only if the Oracle Tuxedo system compatibility functions for setlocale(), strftime(), or nl_langinfo() are used. The functions provided with the UNIX system use a different set and format of files.

qmadmin—Queue manager administration program.

[QMCONFIG=<device>] qmadmin [<device>]

With the commands listed in this entry, qmadmin supports the creation, inspection, and modification of message queues. The universal device list (UDL) maps the physical storage space on a machine on which the Oracle Tuxedo ATMI system is run. An entry in the UDL points to the disk space in which the queues and messages of a queue space are stored. The name of the device (file) on which the UDL resides (or will reside) for the queue space may be specified either as a command line argument or via the environment variable QMCONFIG. If both are specified, the command option is used.

As a system-provided command, qmadmin does not undergo normal initialization, so it does not pick up the value of ULOGPFX from the UBBCONFIG file. As a result, any log entries generated by qmadmin commands are written to the current working directory. This is corrected by setting and exporting the ULOGPFX environment variable to the pathname of the directory in which the userlog is located.

qmadmin uses the greater than sign (>) as a prompt. Arguments are entered separated by white space (tabs and/or spaces). Arguments that contain white space may be enclosed within double quotes; if an argument enclosed within double quotes contains a double quote, the internal double quote must be preceded with a backslash. Commands prompt for required information if it is not given on the command line. A warning message is displayed and the prompt shown again, if a required argument is not entered. Commands do not prompt for information on optional parameters.

A user can exit the program by entering q or <CTRL-d> when prompted for a command. Output from a command may be terminated by pressing BREAK; the program then prompts for the next command. Hitting return when prompted for a command repeats the previously executed command, except after a break.

Output from qmadmin commands is paginated according to the pagination command in use (see the paginate subcommand below).

When qmadmin is initially entered, no queue space is opened. To create a queue space, run qspacecreate; to open it, run qopen. The qaborttrans, qclose, qchangeprio, qchangequeue, qchangetime, qchangeexptime, qcommittrans, qchange, qcreate, qdeletemsg, qinfo, qlist, qprinttrans and qset commands can be executed only when a queue space is open.

The following table lists the qmadmin commands grouped by functional type.

The following sequence shows how to set up a queue.

$ QMCONFIG=/dev/rawfs qmadmin
qmadmin - Copyright (c) 1987 ATT; 1991 USL. All rights reserved.
QMCONFIG=/dev/rawfs
# create the list of devices on which the queue space
# can exist; specify two devices, 80000 and 600
# blocks, respectively
# NOTE: the first one will actually contain the device list
#
# create first device on a raw slice
#
> crdl /dev/rawfs 0 80000
Created device /dev/rawfs, offset 0, size 80000 on /dev/rawfs
#
# create another device on a UNIX file
#
> crdl /home/queues/FS 0 600
Created device /home/queues/FS, offset 0, size 600 on /dev/rawfs
#
# if you want a list of the device list
#
> v Verbose mode is now on

> lidl
universal device index. 0:
      name: /dev/rawfs
      start: 0
      size: 20000
      free space map(1 entry used 47 available):
         size[1]: 79974 addr[1]: 26
universal device index. 1:
      name: /home/queues/FS
      start: 0
      size: 600
      free space map(1 entry used 47 available):
              size[1]: 600 addr[1]: 0
#
# create a queue space
#
> qspacecreate
Queue space name: myqueuespace
IPC Key for queue space: 42000
Size of queue space in disk pages: 50000
Number of queues in queue space: 30
Number of concurrent transactions in queue space: 
Number of concurrent processes in queue space: 30
Number of messages in queue space: 20000
Error queue name: ERRORQ
Initialize extents (y, n [default=n]): y
Blocking factor [default=16]: 16
  ....................
#
# open queue space
#
> qopen myqueuespace
#
# use queue space defaults for queue
> qcreate
Queue name: service1
queue order (priority, time, fifo, lifo): fifo
out-of-ordering enqueuing (top, msgid, [default=none]): top,msgid
retries [default=0]: 1
retry delay in seconds [default=0]: 30
High limit for queue capacity warning (b for bytes used, B for blocks used,
  % for percent used, m for messages [default=100%]): 100m
Reset (low) limit for queue capacity warning [default=0m]: 50
queue capacity command: /usr/app/bin/mailadmin myqueuespace service1
#
# get out of the program
#
> q

The administrator for the queue must be the same as the Oracle Tuxedo administrator. The device on which the queue resides must be owned by the administrator and qmadmin can only be run as the administrator for the queue. All IPC resources allocated for the queue will be owned by the queue administrator and will be created with mode 0600.

qmadmin is supported on any platform on which the Oracle Tuxedo ATMI server environment is supported.

In order to carry out a command that you have configured within a qmadmin() session, such as the qchange ... Queue capacity command, the Windows CreateProcess() function spawns a child process as a DETACHED PROCESS. This type of process does not have an associated console for standard input/output. Therefore, for instance, if you use standard command line syntax to set the qchange ... Queue capacity command to run a built-in command (such as dir or date) and then pipe or redirect the standard output to a file, the file will be empty when the command completes.