PURPOSE

ud, wud - TUXEDO System/T driver program

SYNOPSIS

ud
[-p]
[-ddelay]
[-eerror_limit]
[-r]
[-ssleeptime]
[-ttimeout]
[-n]
	[-u {n | u | j}]
[-Uusrname]
[-Ccltname]
[-Sbuffersize]
ud32 [options]
wud [options]
wud32 [options]

DESCRIPTION

ud reads an input packet from its standard input using Fextread(3fml). The packet must contain a field identified as the name of a service. The input packet is transferred to an FML fielded buffer (FBFR) and sent to the service. If the service that receives the FBFR is one that adds records to a database, ud provides a method for entering bulk fielded data into a database known to TUXEDO System/T.

By using flags (see INPUT FORMAT) to begin the lines of the input packet, you can use ud to test TUXEDO System/T services.

By default, after sending the FBFR to the service, ud expects a return FBFR. The sent and reply FBFRs are printed to ud's standard output; error messages are printed to standard error.

ud32 uses FML32 buffers of type FBFR32.

wud and wud32 are versions of ud and ud32 built using the workstation libraries. On sites supporting just /WS, only the wud and wud32 commands will be present.

OPTIONS

ud supports the following options:

-p: suppress printing of the sent and returned fielded buffers.
-d: expect a delayed reply for every request. delay specifies the maximum delay time in seconds before time out. If time-out occurs, an error message is printed on stderr. If ud receives reply messages for previous requests within the delay time, they will be indicated as delayed RTN packets. Hence, it is possible to receive more than one reply packet within a delay time interval. The -d option is not available for wud on DOS operating systems.
-e error_limit: ud stops processing requests when errors exceed the limit specified in error_limit. If no limit is specified, the default is 25.
-r: ud should not expect a reply message from servers.
-s sleeptime: sleep between sends of input buffers. sleeptime is the time, in seconds, of the sleep.
-t timeout: ud should send requests in transaction mode. timeout is the time, in seconds, before the transaction is timed out. The -d delay and -r (no reply) options are not allowed in combination with the -t option.
-u {n | u | j}: specify how the request buffer is modified before reading each new packet. The n option indicates that the buffer should be re-initialized (treated as new). The u option indicates that the buffer should be updated with the reply buffer using Fupdate(3fml). The j option indicates that the reply buffer should be joined with the request buffer using Fojoin(3fml).
-n: re-initialize the buffer before reading each packet (i.e., treat each buffer as a new buffer). This option is equivalent to -un and is maintained for compatibility.
-U usrname: Use usrname as the user name when joining the application.
-C cltname: Use cltname as the client name when joining the application.
-S buffersize: If the default buffer size is not large enough, the -S option can be used to raise the limit. buffersize can be any number up to MAXLONG.

The -d delay and -r options are mutually exclusive.

INPUT FORMAT

Input packets consist of lines formatted as follows: [flag]fldname<tab>fldvalflag is optional. If flag is not specified, a new occurrence of the field named by fldname with value fldval is added to the fielded buffer. If flag is specified, it should be one of:

+: occurrence 0 of fldname in FBFR should be changed to fldval.
-: occurrence 0 of fldname should be deleted from FBFR. The tab character is required; fldval is ignored.
=: the value in fldname should be changed. In this case, fldval specifies the name of a field whose value should be assigned to the field named by fldname.
#: the line is treated as a comment and is ignored.

If fldname is the literal value SRVCNM, fldval is the name of the service to which FBFR is to be passed.

Lengthy field values can be continued on the next line by having the continuation line begin with a tab.

A line consisting only of the newline character ends the input and sends the packet to ud.

If an input packet begins with a line consisting of the character n followed by the newline character, the FBFR is reinitialized. FBFR reinitialization can be specified for all packets with the -un option on the command line.

To enter an unprintable character in the input packet, use the escaping convention followed by the hexadecimal representation of the desired character (see ASCII(5)). An additional backslash is needed to protect the escape from the shell. A space, for example, can be entered in the input data as \\20. ud recognizes all input in this format, but its greatest usefulness is for non-printing characters.

PROCESSING MODEL

Initially, ud reads a fielded buffer from its standard input and sends it to the service whose name is given by the fldval of the line where fldname equals SRVCNM. Unless the -r option is selected, ud waits for a reply fielded buffer. After obtaining the reply, ud reads another fielded buffer from the standard input. In so doing, ud retains the returned buffer as the current buffer. This means that the lines on the standard input that form the second fielded buffer are taken to be additions to the buffer just returned. That is, the default action is for ud to maintain a current buffer whose contents are added to by a set of input lines. The set is delimited by a blank line. ud may be instructed to discard the current buffer (that is, to reinitialize its FBFR structure) either by specifying the -un option on the command line, or by including a line whose only character is the letter n as the first line of an input set. ud may be instructed to merge the contents of the reply buffer into the request buffer by specifying either the -uu option (Fupdate is used) or the -uj option (Fojoin is used).

SECURITY

If ud is run in a security application, it requires an application password to access the application. If standard input is a terminal, ud prompts the user for the password with echo turned off on the reply. However, since ud accepts bulk input on standard input, standard input will typically be a file and not a terminal. In this case, the password is retrieved from the environment variable, APP_PW. If this environment variable is not specified and an application password is required, then ud will fail.

PORTABILITY

These commands are supported as TUXEDO System/T-supplied clients on UNIX and MS-DOS operating systems.

ENVIRONMENT VARIABLES

FLDTBLDIR and FIELDTBLS must be set and exported. FLDTBLDIR must include $TUXDIR/udataobj in the list of directories. FIELDTBLS must include Usysflds as one of the field tables.

APP_PW must be set to the application password in a security application if standard input is not from a terminal. TPIDATA must be set to the application specific data necessary to join the application in a security application with an authentication server if standard input is not from a terminal.

WSNADDR, WSDEVICE and optionally WSTYPE must be set if access is from a workstation. See compilation(5) for more details on setting environment variables for client processes.

DIAGNOSTICS

ud fails if it cannot become a client process, if it cannot create the needed FBFRs, or if it encounters a UNIX System error. It also fails if it encounters more than 25 errors in processing a stream of input packets. These can be syntax errors, missing service names, errors in starting or committing a transaction, time-outs and errors in sending the input FBFR or in receiving the reply FBFR.

NOTICES

The final fielded buffer in the input stream should be terminated by a blank line.

EXAMPLES


$ ud <EOF>
SRVCNM	BUY
CLIENT	J.  Jones
ADDR  	21 Valley Road
STOCK 	AAA
SHARES	100
<CR>
+SRVCNM	SELL
+STOCK 	XXX
+SHARES	300
STOCK	YYY
SHARES	150
<CR>
n
SRVCNM	BUY
CLIENT	T.  Smith
ADDR  	1 Main Street
STOCK 	BBB
SHARES	175
<CR>
+SRVCNM	SELL
+STOCK 	ZZZ
+SHARES	100
<CR>
EOF
$

In this example, ud first sends a fielded buffer to the service BUY with CLIENT field set to J. Jones, ADDR field set to 21 Valley Road, STOCK field to AAA, and SHARES field set to 100.

When the fielded buffer is returned from the BUY service, ud uses the next set of lines to change SRVCNM to SELL, STOCK to XXX, and SHARES to 300. Also, it creates an additional occurrence of the STOCK field with value YYY and an additional occurrence of the SHARES field with value 150. This fielded buffer is then sent to the SELL service (the new value of the SRVCNM field).

When SELL sends back a reply fielded buffer, ud discards it by beginning the next set of lines with a line containing only the character n. ud then begins building an entirely new input packet with a SRVCNM of BUY, CLIENT of value T. Smith, and so on.