This chapter covers the use of the Workstation on UNIX workstations. The material is organized under the following section headings:
What This Chapter Is About
wmio(1)
The source code for client programs running on UNIX workstations is the same as that for client programs within the BEA TUXEDO system administrative domain (that is, native clients). You have available all of the ATMI functions, FML functions, and the BEA TUXEDO system data entry system for defining and managing forms.
The BEA TUXEDO Programmer's Guide covers the use of the ATMI calls in considerable detail. There is a separate chapter dealing with client programs.
The BEA TUXEDO FML Programmer's Guide and the BEA TUXEDO Data Entry System Guide are useful for information on those two special subjects. Sections 1 and 3c of the BEA TUXEDO Reference Manual are the final authority for all BEA TUXEDO system commands and functions.
Workstation client programs are compiled and linked with the Listing 3-1 shows an example of the Coding and Building Clients
References to Other Guides
Building Clients
buildclient(1) command. If you are building a Workstation client on a native node (that is, one on which the complete BEA TUXEDO system is installed), use the -w option. This specifies that the client should be built using the workstation libraries. On a native node, where both native and workstation libraries are present, the default is to use the native libraries. The -w option ensures that the correct libraries for a workstation client are used. On a workstation, where only the workstation libraries are present, it is not necessary to use the -w.
buildclient(1) command line on a native node.
Listing 3-1
buildclient Command Line
TUXDIR=/var/opt/tuxedo CC=ncc; export TUXDIR CC
buildclient -w -o wsclt -f wsclt.c -f "userlib1.a userlib2.a"
The -o option provides a name for your executable file. Input files are specified with a -f firstfiles option in Listing 3-1 to indicate that they are called in ahead of system libraries. buildclient needs TUXDIR to locate system libraries. CC defaults to cc, but can be set to another compiler as in the example.
Two system-delivered clients are available on UNIX workstations. These are standard BEA TUXEDO system clients that have been slightly modified for workstation use, which is shown by the w prefix.
wmio(1)
wud(1)
FML buffers to BEA TUXEDO system servers
If the BEA TUXEDO system second-level security has been specified for an application, the system clients prompt the user for the application password. If the client program is being run from a script, which is a common occurrence with wud, the password is read from the APP_PW environment variable. Do not confuse the environment variable with the similar configuration file parameter, SECURITY, for which the value APP_PW enables the security feature.
After the client programs have been developed and tested, they can be moved to the workstations where they will be available to users.
APPDIR
$TUXDIR/include
atmi.h
$TUXDIR/bin
wmio and wud
$TUXDIR/locale/C
$TUXDIR/lib
Workstation clients make use of several environment variables. The following are checked by tpinit() when the workstation client attempts to join the application:
WSENVFILE
WSNADDR
TCP/IP addresses may be specified in the following forms:
"//host.name:port_number"
"//#.#.#.#:port_number"
Note: If you are specifying TCP/IP addresses for a Windows NT workstation, omit the quotation marks.
In the first format, the domain finds an address for hostname using the local name resolution facilities (usually DNS). hostname must be the local machine, and the local name resolution facilities must unambiguously resolve hostname to the address of the local machine.
In the second example, the "#.#.#.#" is in dotted decimal format. In dotted decimal format, each # should be a number from 0 to 255. This dotted decimal number represents the IP address of the local machine.
In both of the above formats, port_number is the TCP port number at which the domain process will listen for incoming requests. port_number can be either a number between 0 and 65535 or a name. If port_number is a name, then it must be found in the network services database on your local machine.
The address can also be specified in hexadecimal format when preceded by the characters "0x". Each character after the initial "0x" is a number between 0 and 9 or a letter between A and F (case insensitive). The hexadecimal format is useful for arbitrary binary network addresses such as IPX/SPX or TCP/IP.
The address can also be specified as an arbitrary string. The value should be the same as that specified for the -n netaddr option of the wsl(5).
You can specify more than one address by including a comma-separated list of pathnames for WSNADDR. Addresses are tried in order until a connection is established. You can specify any item in an address list as a parenthesized grouping of pipe-separated network addresses. For example,
WSNADDR="(//m1.acme.com:3050|//m2.acme.com:3050), //m3.acme.com:3050"
The BEA TUXEDO system randomly selects one of the parenthesized addresses. This strategy distributes the load randomly across a set of listener processes. If this is being specified for a Windows NT workstation, leave off the quotation marks. Addresses are tried in order until a connection is established.
WSDEVICE
/dev/tcp for TCP/IP and to /dev/nspx for the SPX networking protocol.
WSTYPE
tpinit() when invoked by a workstation client to negotiate encode/decode responsibilities with the native site. An unspecified WSTYPE always causes encoding, even if it is also unspecified on the native site. The only way to ensure that encode/decode is turned off is to explicitly specify the same WSTYPE value for both sites.
WSRPLYMAX
tpinit() to set the maximum amount of core memory that ATMI functions use for buffering application replies before they are dumped to disk. Replies that are not being waited for (using tpgetrply()), and unsolicited messages are buffered in this area. When this area gets filled with one or more messages, the overflow is written to a disk file. The system default limit for this is 32,000 bytes. The available memory on your machine is the key factor in deciding whether you should use WSRPLYMAX to set a lower limit. Writing replies to disk causes a substantial reduction in performance.
Other environment variables may be needed by Workstation clients on a UNIX workstation depending on what BEA TUXEDO system features are being used. The compilation(5) reference page recaps which variables are needed under what circumstances.
When tpinit() is called, an environment file is read if it exists. Listing 3-2 shows a sample file that could be used for two different applications.
Listing 3-2 Environment File
TUXDIR=/opt/tuxedo
[application1]
;this is a comment
/* this is a comment */
#this is a comment
//this is a comment
set FIELDTBLS=app1_flds
set FLDTBLDIR=/opt/app1/udataobj
[application2]
FIELDTBLS=app2_flds
FLDTBLDIR=/opt/app2/udataobj
The format of the file is as follows:
where variable=valueorset variable=value
variable must begin with an alphabetic or underscore character and contain only alphanumeric or underscore characters, and value may contain any character except newline.
value, strings of the form ${env} are expanded using variables already in the environment. Forward referencing is not supported and if a value is not set, the variable is replaced with the empty string. Backslash (\) may be used to escape the dollar sign and itself. All other shell quoting and escape mechanisms are ignored and the expanded value is placed into the environment.
[
where label]label is the name of the section and follows the same rules for variable above. The label is silently truncated if longer than 31 characters.[] also indicates the global section. Other variables are put into the environment only if the label matches the application label specified for the application.
The function If Using tuxreadenv
tuxreadenv(3c) can be used to read the environment file for a particular label:
void tuxreadenv(char *file, char *label)
file is NULL, then a default file name is used. The default file names for various platforms are as follows:
C:\TUXEDO\TUXEDO.ENV
TUXEDO.ENV in the system directory
SYS:SYSTEM\TUXEDO.ENV
/usr/tuxedo/TUXEDO.ENV or /var/opt/tuxedo/TUXEDO.ENV
If the value of label is NULL, then only variables in the global section are put into the environment. For other values of label, the global section variables plus any variables in a section matching the label are put into the environment.
An error message is printed to the userlog if there is a memory failure, if a non-null file name does not exist, or if a non-null label does not exist.
Each time tpinit() is called (either explicitly or implicitly by calling another ATMI function), tuxreadenv() is called automatically in Workstation clients. If WSENVFILE is set in the environment, then it designates the environment file; otherwise, NULL is passed to tuxreadenv() for the file name so that the default file is used. If WSAPP is set in the environment, then it is to be used as the section label in the environment file; otherwise, NULL is passed to tuxreadenv() for the label name. Application clients may also call tuxreadenv() explicitly.
The environment is implemented and available in different ways on different platforms. A uniform interface to the environment is provided via the existing tuxgetenv(3c) and tuxputenv(3c) functions. These functions provide access to (a) all variables from the specified WSENVFILE file for the specified WSAPP label (or the defaults if not specified), and (b) the environment variables in the operating system environment.