ud, wud(1)


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| Command Reference \| Local Topics \| Previous Topic \| Next Topic \| Contents

ud, wud(1)

Name

ud, wud—BEA Tuxedo ATMI 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() (see Fextread, Fextread32(3fml) for details). 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 the BEA Tuxedo ATMI system.

By using flags (see "Input Format") to begin the lines of the input packet, you can use ud to test BEA Tuxedo ATMI 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 that support only Workstation, only the wud and wud32 commands are provided.

Options

ud supports the following options.

-p

Suppresses printing of the fielded buffers that were sent and returned.

-d

Expects a delayed reply for every request. delay specifies the maximum delay time, in seconds, before timeout. If timeout occurs, an error message is printed on stderr. If ud receives reply messages for previous requests within the delay time, they are 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

Sleeps 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}

Specifies how the request buffer is modified before reading each new packet. The n option indicates that the buffer should be reinitialized (treated as new). The u option indicates that the buffer should be updated with the reply buffer using Fupdate(). The j option indicates that the reply buffer should be joined with the request buffer using Fojoin(). (See Fupdate, Fupdate32(3fml) and Fojoin, Fojoin32(3fml) for details.)

-n

Reinitializes the buffer before reading each packet (that is, treat each buffer as a new buffer). This option is equivalent to -un and is maintained for compatibility.

-U usrname

Uses usrname as the username 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. The value of 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 fldval

flag 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 the following:

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; it 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 putting a tab at the beginning of the continuation line.

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 escape convention followed by the hexadecimal representation of the desired character. (For details, see ascii(5) in a UNIX reference manual.) 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 in which 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 in which the only character is the letter n, specified 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 is typically a file rather than 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 fails.

Portability

These commands are supported on any platform on which the BEA Tuxedo ATMI server environment is supported.

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, timeouts, 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 the CLIENT field set to J. Jones, the ADDR field set to 21 Valley Road, the STOCK field set to AAA, and the 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 a value of 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 SRVCNM set to BUY, CLIENT set to T. Smith, and so on.