---

4. BEA TUXEDO Workstation for MS-DOS Workstations

---

What This Chapter Is About

This chapter covers the use of the BEA TUXEDO Workstation feature on MS-DOS workstations. The material is organized under the following section headings:

• Coding and building clients

• System-delivered clients

  • wud(1)

• Running BEA TUXEDO clients on an MS-DOS workstation

  • Directory structure to support Workstation clients

  • Environment variables for Workstation clients

Prerequisites

The BEA TUXEDO System/Workstation for MS-DOS requires a workstation running MS-DOS 3.21 or later and a minimum of 1M of RAM.

The software to support network communications must be installed. The Workstation has been tested with the Sockets interface provided in the Novell LAN Workplace for DOS version 4.2 and compiled using the LAN Workplace Toolkit for DOS version 4.1 over TCP/IP. The toolkit is only required while developing applications and not needed for a runtime system.

The SPX software has been tested using the NetWare client and compiled using the NetWare client SDK version 1.0. The NetWare client SDK is only required while developing applications and not needed for a runtime system.

The libraries are compiled using the Microsoft C++ Version 1.5, using the Large memory model. The Medium memory model is no longer supported.

Coding and Building Clients

Client programs for MS-DOS workstations are the same as client programs within the BEA TUXEDO system administrative domain, with one exception:

• The BEA TUXEDO system data entry system and the form handler mio(1) are not available

You do have available all of the ATMI functions. You have all FML functions with the following exceptions (and their VIEW counterparts):

Fboolco()    Fboolev()    Fboolpr()       Ffloatev()

The FML function Ffindocc is present but is not able to search for regular expressions. The external variable Ferror is redefined to FMLerror.

Buffer Size Limitation

On DOS and WINDOWS workstations, message buffer sizes are limited to 64K less the size of the message header (currently under 400 bytes).

References to Other Guides

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 is useful for information on the Field Manipulation Language. Reference pages in the BEA TUXEDO Reference Manual are the final authority for all BEA TUXEDO system commands and functions.

Building Clients

Workstation client object files are link edited with the buildclt(1) command. While the syntax of the command is straightforward, the usage varies according to the compilation system used.

buildclt syntax

buildclt has the following options:

-o name

specifies the file name of the executable file being created. The default is client.exe.

-c {m | i}

specifies the compilation system to be used. m stands for Microsoft compilation system. i stands for the IBM OS/2 Cset2 compiler and is only used on OS/2 32 bit. Microsoft is the default. The system specified imposes other requirements discussed below.

-m {m | l}

specifies the medium or large memory model. The default is l. The medium memory model is not supported under DOS.

-f firstfiles

indicates one or more object files to be included before the BEA TUXEDO system libraries. -f can also be used to pass options to the compiler or linker. If more than one file name is specified, the names are separated by white space and the list is enclosed in quotation marks. The -f option can appear more than once.

-l libfiles

specifies libraries to be included after the BEA TUXEDO system libraries. If more than one file name is specified, the names are separated by white space and the list is enclosed in quotation marks. The -l option can appear more than once.

-d deffile

specifies a module definition file used for linking a Windows program.

-W

indicates a Windows or Windows NT client is being built.

-O

indicates an OS/2 client is being built.

Microsoft Compilation Environment

The Microsoft C environment expects to find library directory names in the environment variables INCLUDE and LIB. They might be set as follows:

INCLUDE=C:\C600\INCLUDE;C:\TUXEDO\INCLUDE
LIB=C:\NET\TOOLKIT\LIB;C:\C600\LIB;C:\TUXEDO\LIB

The C:\NET directory is the location of the LAN Workplace Toolkit.

buildclt can be used to link edit the executable. The client source files should be compiled separately using the CL command. The -f option is used to pass options to the LINK command, as well as to name the input object files.

Examples of possible options are:

-f /SE:200     # to set the number of segments used to 200
-f /ST:10000   # to set default stack size to 10000 bytes
-f /CO         # to create a file that can be debugged by Codeview
               # (assumes the file was compiled with the -Zi option)

buildclt Examples

Listing 4-1 shows some sample buildclt command lines. All of the examples show an executable named emp.exe being built.

Listing 4-1 Example of buildclt(1) command lines

---

DOS:
buildclt -cm -ml -o emp.exe -f "/CO/ST:10000/SE:200" -f emp.obj -l llibsock.lib
WINDOWS:
buildclt -W -cb -mm -o emp.exe -f "-v emp.obj" -l twlbsock.lib -d emp.def
buildclt -W -cm -mm -o emp.exe -f "/CO emp.obj" -l wlibsock.lib -d emp.def

---

System-delivered Client

A system-delivered client is available on MS-DOS workstations. This is a standard BEA TUXEDO system client that has been slightly modified for workstation use, which is shown by the w prefix.

wud(1)

The BEA TUXEDO driver program that sends FML buffers to BEA TUXEDO system servers

Application Password when Running from a Script

If BEA TUXEDO 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.

Running BEA TUXEDO System Clients on a Workstation

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

Directory Structure to Support /WS Clients

The following directories should be present under the directory designated as TUXDIR.

bin

BEA TUXEDO system commands and system clients, for example, wud

locale/C

international message directory (English version). Other language directories may be present under locale.

Environment Variables

Workstation clients make use of several environment variables. The following are checked by tpinit() when the client attempts to join the application:

WSENVFILE

Names a file containing environment variable settings to be set in the client's environment. All of the other environment variables needed by client programs can be contained in this file. The format of this file is described in further detail below.

WSNADDR

Specifies the network address of the workstation listener process through which clients gain access to the application.

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 either be 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 NLSADDR parameter in the NETWORK section of the configuration file.

More than one address can be specified if desired by specifying a comma-separated list of pathnames for WSNADDR. Addresses are tried in order until a connection is established. Any member of an address list can be specified 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. Addresses are tried in order until a connection is established.

WSTYPE

is used within 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 specify the same WSTYPE value for both sites.

WSDEVICE

In Release 6.4 or higher, this variable is never required. In prior releases, it is required while using the SPX protocol under DOS or Windows. It should be set to /dev/nspx for the SPX networking protocol.

WSRPLYMAX

is used by 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 an MS-DOS workstation depending on what BEA TUXEDO system features are being used. Two MS-DOS conditions apply:

• Environment variables that take directory lists, for example, FLDTBLDIR and VIEWDIR, must observe MS-DOS conventions.

  • Directory names are separated by semicolons rather than colons.

  • Pathname components are separated by backslashes rather than slashes.

  • The default field table file looked for by mkfldhdr(1) is fld.tbl in the UNIX environment. The default output file is fld.tbl.h, which is an illegal file name under MS-DOS. In the MS-DOS environment, the default names are fldtbl and fldtbl.h.

• Binary view description file names are given a.vv suffix rather than the single .V of the case-sensitive UNIX environment.

The compilation(5) manual page recaps which variables are needed under what circumstances.

When tpinit() is called, an environment file will be read if it exists. Here is an example file that could be used for two different applications.

TUXDIR=C:\TUXEDO
[application1]
;this is a comment
/* this is a comment */
#this is a comment
//this is a comment
SET FIELDTBLS=APP1_FLDS
set FLDTBLDIR=C:\APP1\UDATAOBJ
[application2]
FIELDTBLS=APP2_FLDS
FLDTBLDIR=C:\APP2\UDATAOBJ

The format of the file contents is as follows:

• Any leading space and tab characters on each line are ignored and are not considered in the following points.

• Lines containing variables to be put into the environment are of the form

  variable=value
  or 
  set variable=value

  where variable must begin with an alphabetic or underscore character and contain only alphanumeric or underscore characters, and value may contain any character except newline.

• Within the 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.

• Lines beginning with slash (/), pound sign (#), or exclamation point (!) are treated as comments and ignored. Lines beginning with other characters besides these comment characters, a left square bracket, or an alphabetic or underscore character are reserved for future use; their use is undefined.

• The file is partitioned into sections by lines of the form

  [label]

  where label is the name of the section and follows the same rules for variable above. The label will be silently truncated if longer than 31 characters.

• Variable lines between the top of the file and the first label are put into the environment for all applications; this is the global section. A label of [] will also indicate the global section. Other variables are put into the environment only if the label matches the application label specified for the application.

The following function can be used to read the environment file for a particular label.

void tuxreadenv(char *file, char *label)

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

DOS, Windows, OS/2

C:\TUXEDO\TUXEDO.ENV

Macintosh

TUXEDO.ENV in the system preferences directory

NETWARE

SYS:SYSTEM\TUXEDO.ENV

POSIX

/usr/tuxedo/TUXEDO.ENV or /var/opt/tuxedo/TUXEDO.ENV

If 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() will be called automatically in Workstation clients. If WSENVFILE is set in the environment, then it will be used as the name of the environment file; otherwise, NULL will be passed to tuxreadenv() for the file name such that the default file is used. If WSAPP is set in the environment, then it will be used as the section label in environment file; otherwise, NULL will be passed to tuxreadenv() for the label name. Application clients may also call tuxreadenv() explicitly.

The environment is implemented and available differently 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 all variables set both from the specified WSENVFILE file for the specified WSAPP label (or the defaults if not specified) and the environment variables set via the operating system environment, if supported (in the case of MS Windows, the DOS environment is available).

---

---