Using the BEA Tuxedo ATMI Workstation Component

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Using the Workstation Component

The following sections describe using the BEA Tuxedo ATMI Workstation component on both Windows and UNIX systems:


Writing Client Programs

You can develop client programs targeted for workstations in the same way that you develop client programs within the BEA Tuxedo system administrative domain (that is, native clients). With a few exceptions, all ATMI and FML functions available to the native client are also available to the Workstation client.

Note: tpadmcall() is an example of an ATMI function that is available to the native client but not to the Workstation client.

Interoperability Restrictions for Workstation Clients

Interoperability between BEA Tuxedo release 7.1 or later Workstation clients and applications based on pre-7.1 releases of the BEA Tuxedo system is supported in any of the following situations:

A BEA Tuxedo release 7.1 or later Workstation client with multiple threads in a single context cannot interoperate with a pre-7.1 release of the BEA Tuxedo system.

Building Client Programs

You compile and link-edit Workstation client programs using the 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 to indicate the client should be built using the workstation libraries. Otherwise, on a native node, where both native and workstation libraries are present, the default is to use the native libraries. In this case, using 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 option.

The following listing shows an example of the buildclient(1) command line on a native node.

Listing 2-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 output file. Input files are specified with the -f firstfiles option to indicate that they are link-edited before system libraries. As indicated in the example, you must define the TUXDIR environment variable to ensure that the buildclient command can locate system libraries. CC defaults to cc but can be set to another compiler, as shown in the example.

See Also


Using BEA Tuxedo System-Supplied Clients

wud and wud32 are BEA Tuxedo system-supplied driver programs provided for workstations. These driver programs are based on the standard BEA Tuxedo client programs, ud and ud32, that have been built using the workstation libraries.

Use wud(1) to send FML buffers to BEA Tuxedo system servers. Use wud32 with fielded FML32 buffers of type FBFR32.

Using wud in a Security Application

If wud is run in a security application, it requires an application password to access the application. If standard input is from a terminal, wud prompts the user for an application password. If you are running the client program from a script, which is a common occurrence with wud, the password is retrieved from the environment variable APP_PW. If this environment variable is not specified and an application password is required, then wud fails.

Do not confuse the APP_PW environment variable with the similar configuration file parameter, SECURITY, for which the value APP_PW enables the security feature.

See Also


Running BEA Tuxedo System Clients on a Workstation

After the client programs have been developed and tested, they can be moved to the workstations where they will be available to users.

Verifying the Directory Structure on Workstation Clients

The following table describes the directory structure on a Workstation client after you have installed the Workstation component of the BEA Tuxedo system.

Windows Directory
UNIX Directory
Contains the client executables. These executables are commonly kept in the directory from which the application is run.
Contains BEA Tuxedo system commands and system clients such as wud.
Contains copylib entries for use in COBOL programs.
Contains BEA Tuxedo system header files such as atmi.h.
Contains run-time libraries.
Contains message catalogs for the default locale (U.S. English).
Contains several subdirectories with sample applications.

Setting Environment Variables

Workstation clients make use of several environment variables. The following table shows the environment variables that are checked by tpinit(3c) or TPINITIALIZE(3cbl) when the Workstation client attempts to join the application. For details on setting these environment variables, see Defining Workstation Clients" in Setting Up a BEA Tuxedo Application.

Environment Variable
Specifies the code-set encoding name that the workstation machine running BEA Tuxedo 8.1 or later includes in an allocated MBSTRING typed buffer. When a Workstation client allocates and sends an MBSTRING buffer, the code-set encoding name defined in TPMBENC is automatically added as an attribute to the buffer and sent with the buffer data to the destination server process.
When the workstation machine receives an MBSTRING buffer, and assuming another environment variable named TPMBACONV is set, the code-set encoding name defined in TPMBENC is automatically compared to the code-set encoding name in the received buffer; if the names are not the same, the MBSTRING buffer data is automatically converted to the encoding defined in TPMBENC before being delivered to the Workstation client.
TPMBENC has no default value. For a Workstation client using MBSTRING typed buffers, TPMBENC must be defined on the workstation machine.

Note: TPMBENC is used in a similar way for FLD_MBSTRING fields in an FML32 typed buffer.

Specifies whether the workstation machine running BEA Tuxedo 8.1 or later automatically converts the data in a received MBSTRING buffer to the encoding defined in TPMBENC. By default, the automatic conversion is turned off, meaning that the data in the received MBSTRING buffer is delivered to the Workstation client as is—no encoding conversion. Setting TPMBACONV to any non-NULL value, say Y (yes), turns on the automatic conversion.

Note: TPMBACONV is used in a similar way for FLD_MBSTRING fields in an FML32 typed buffer.

Specifies whether the workstation machine running BEA Tuxedo 8.1 or later caches Document Type Definition (DTD), XML schema, and entity files; specifically, whether the Apache Xerces-C++ parser running on the Workstation client caches the DTD and XML schema files when validation is required, or caches external entity files called out in the DTD. By default, the caching is turned on (Y). Setting URLENTITYCACHING to N (no) turns off the caching.
Applies only if URLENTITYCACHING=Y (yes) or is not set; for details, see the description of URLENTITYCACHING in this table.
Specifies the directory in which the workstation machine running BEA Tuxedo 8.1 or later caches DTD, schema, and entity files; specifically, where the Apache Xerces-C++ parser running on the Workstation client caches the DTD, XML schema, and entity files. The URLENTITYCACHEDIR variable specifies the absolute pathname for the cached files. If URLENTITYCACHEDIR is not specified, the default directory becomes URLEntityCachedir, which will be created in the current working directory of the Workstation client process provided that the appropriate write permissions are set.
Specifies whether the workstation machine running BEA Tuxedo 7.1 or later is allowed to interoperate with pre-release 7.1 BEA Tuxedo applications. Setting the variable to Y (WSINTOPPRE71=Y) allows interoperability.
The number of packets per application.
Device name to be used to access the network. This variable is only required when the BEA Tuxedo system is using the TLI networking interface.
Name of a file containing environment variable settings to be set in the client's environment.
The network address used by the Workstation client when connecting to the workstation listener or workstation handler. This variable, along with the WSFRANGE variable, determines the range of TCP/IP ports to which a Workstation client will attempt to bind before making an outbound connection. This address must be a TCP/IP address.
The range of TCP/IP ports to which a Workstation client process attempts to bind before making an outbound connection. The WSFADDR parameter specifies the base address of the range. The default is 1.
The network address of the workstation listener (WSL) process through which clients gain access to the application. Use the value specified in the application configuration file for the workstation listener to be called. If the value begins with the characters 0x, the system interprets it as a string of hexadecimal digits; otherwise, the system interprets it as ASCII characters.
Maximum amount of core memory that ATMI functions use for buffering application replies before they are dumped to disk. Used by tpinit(3c) and TPINITIALIZE(3cbl). Replies obtained using tpgetrply(3c), TPGETRPLY(3cbl), and unsolicited messages are buffered in this area. When this area is filled with one or more messages, the overflow is written to a disk file. The system default limit is 256,000 bytes. Whether you use WSRPLYMAX to set a lower limit depends on the amount of available memory on your machine. Writing replies to disk causes a substantial reduction in performance.
Workstation type. Used within tpinit(3c) and TPINITIALIZE(3cbl) when invoked by a Workstation client to negotiate encode/decode responsibilities with the native site. If you do not specify WSTYPE, the system performs encoding, even if it is also unspecified on the native site.You must explicitly specify the same WSTYPE value for both sites to ensure that the encode/decode feature is turned off.

Other environment variables may be needed by Workstation clients on a UNIX workstation depending on the BEA Tuxedo system features being used. Reference page compilation(5) in BEA Tuxedo File Formats, Data Descriptions, MIBs, and System Processes Reference explains which variables are needed under what circumstances.

Creating an Environment File

If you have created an environment file, it is read when tpinit(3c) or TPINITIALIZE(3cbl) is called. The following listing shows a sample file that could be used for two different applications.

Listing 2-2 Environment File
;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

The format of the file is as follows:

Using tuxreadenv

When you call the tuxreadenv(3c) function, it reads the environment file and adds the environment variables to the environment for the entire process, independent of platform. These variables are available using tuxgetenv(3c) and can be reset using tuxputenv(3c).

void tuxreadenv(char *file, char *label)

If file is NULL, then a default filename is used. The default filenames for various platforms are as follows:

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 under the following conditions:

Each time tpinit(3c)is called (either explicitly or implicitly by calling another ATMI function), tuxreadenv(3c) 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 filename 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 the following:

See Also


How a Multithreaded or Multicontexted Workstation Client Joins an Application

To join a BEA Tuxedo application, a multithreaded Workstation client must always call tpinit() with the TPMULTICONTEXTS flag set, even if the client is running in single-context mode.

See Also

  Back to Top       Previous  Next