TUXEDO /Workstation for MS-DOS Workstations

What this Chapter is About

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

Prerequisites

The /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 DOSversion and compiled using the Lan Workplace Toolkit for DOS 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 System/T administrative domain, with one exception:

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

he 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. The BEA TUXEDO Reference Manual: Section 1 and BEA TUXEDO Reference Manual: Section 3c are the final authority for all System/T 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
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 he 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
one or more object files to be included before the System/T 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 System/T 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 a 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

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

Fig. 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 System/T client that has been slightly modified for workstation use, which is shown by the w prefix.

wud(1)
the TUXEDO System/T driver program that sends FML buffers to System/T servers

Application Password when Running from a Script

If TUXEDO System/T 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 System/T 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
System/T commands and system clients, for example, wmio, 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 a workstation listener process through which clients gain access to the application.

TCP/IP addresses may be specified in the following forms: (If this is being specified for a Windows NT workstation, leave off the quotation marks.) 


"//host.name:port_number"
"//#.#.#.#:port_number"

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"

TUXEDO 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 in 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 a MS-DOS workstation depending on what System/T 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 semi-colons 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 filenames 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 /WS 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(3) and tuxputenv(3) 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).