|
|
|
|
|
|
Tuxedo Commands
The following information is excerpted from the Tuxedo Online Documentation. These are some of the most commonly used Tuxedo commands used for adapter development. For additional details and a complete list of Tuxedo functions and commands, see http://edocs.beasys.com/tuxedo/tux65/index.htm.
Following is an alphabetical list of the the commands described in this section.
|
Refer to |
|---|
buildclient
Function
Construct a BEA Tuxedo client module
Synopsis
buildclient [ -C ] [ -v ] [ {-r rmname | -w } ] [ -o name] [ -f firstfiles] [ -l lastfiles] Description
buildclient is used to construct a BEA Tuxedo client module. The command combines the files supplied by the -f and -l options with the standard BEA Tuxedo libraries to form a load module. The load module is built by buildclient using the default C language compilation command defined for the operating system in use. The default C language compilation command for the UNIX System is the cc command described in UNIX System reference manuals.
rmname:rmstructure_name:library_names
(See the buildtms command in the BEA Tuxedo Reference Manual at http://edocs.beasys.com/tuxedo/tux65/index.htm for further details.) Using the rmname value, the entry in $TUXDIR/udataobj/RM is used to include the associated libraries for the resource manager automatically and to set up the interface between the transaction manager and resource manager properly. The value Tuxedo/D includes the libraries for the Tuxedo System/D resource manager. The value Tuxedo/SQL includes the libraries for the Tuxedo System/SQL resource manager. Other values can be specified as they are added to the resource manager table. If the -r option is not specified, the default is that the client is not associated with a resource manager. Refer to the ubbconfig reference page.
Environment Variables
Examples
CC=ncc CFLAGS="-I /APPDIR/include"; export CC CFLAGS
buildclient -o empclient -f emp.c -f "userlib1.a userlib2.a"
buildserver
Function
Construct a BEA Tuxedo server load module
Synopsis
buildserver [-C] [-s { @filename | service[,service...][:func] |
:func } ] [-n maxdynam] [-v] [-o outfile] [-f firstfiles]
[-l lastfiles] [{-r|-g} rmname] [-k]Description
buildserver is used to construct a BEA Tuxedo server load module. The command combines the files supplied by the -f and -l options with the standard server main routine and the standard BEA Tuxedo libraries to form a load module. The load module is built by the cc(1) command, which buildserver invokes. (See cc in any UNIX System reference manual.) The options to buildserver have the following meaning:
-s { @filename | service[,service...][:func] | :func } ]
specifies the names of services that can be advertised when the server is booted. Service names (and implicit function names) must be less than or equal to 15 characters in length. An explicit function name (that is, a name specified after a colon) can be up to 128 characters in length. Names longer than these limits are truncated with a warning message. When retrieved by tmadmin or TM_MIB, only the first 15 characters of a name are displayed. (See servopts(5).) All functions that can be associated with a service must be specified with this option. In the most common case, a service is performed by a function that carries the same name; that is, the x service is performed by function x. For example, the specification
-s x,y,z
will build the associated server with services x, y, and z, each to be processed by a function of the same name. In other cases, a service (or several services) may be performed by a function of a different name. The specification
-s x,y,z:abc
builds the associated server with services x, y, and z, each to be processed by the function abc. Spaces are not allowed between commas. Function name is preceded by a colon. In another case, the service name may not be known until runtime. Any function that can have a service associated with it must be specified to buildserver. To specify a function that can have a service name mapped to it, put a colon in front of the function name. For example, the specification
-s :pqr
builds the server with a function pqr, which can have a service association. Tpadvertise could be used to map a service name to the pqr function. A filename can be specified with the -s option by prefacing the filename with the '@' character. Each line of this file is treated as an argument to the -s option. You may put comments in this file. All comments must start with the '#' character. This file can be used to specify all the functions in the erver that may have services mapped to them. The -s option may appear several times. Note that services beginning with the \Q_' or '.' character are reserved for system use, and buildserver will fail if the -s option is used to include such a service in the server.
Environment Variables
Same as buildclient.
Examples
The following example shows how to specify the resource manager (-r Tuxedo/SQL) libraries on the buildserver command line:
buildserver -r Tuxedo/SQL -s OPEN_ACCT -s CLOSE_ACCT -o ACCT
-f ACCT.o -f appinit.o -f util.o
The following example shows how buildserver can be supplied CC and CFLAGS variables and how -f can be used to supply a -lm option to the CC line to link in the math library:
CFLAGS=-g CC=/bin/cc buildserver -r Tuxedo/SQL -s DEPOSIT
-s WITHDRAWAL -s INQUIRY -o TLR -f TLR.o -f util.o -f -lm
The following example shows use of the buildserver command with no resource manager specified:
buildserver -s PRINTER -o PRINTER -f PRINTER.o
tmadmin
Function
BEA Tuxedo bulletin board command interpreter
Synopsis
tmadmin [ -r ] [ -c ] [ -v ]
Description
With the commands listed below, tmadmin provides for inspection and modification of bulletin boards and associated entities in either a uniprocessor, multiprocessor or networked environment. The TUXCONFIG and TUXOFFSET environment variables are used to determine the location and offset where the BEA Tuxedo configuration file has been loaded. If tmadmin is invoked with the -c option, it enters configuration mode. The only valid commands are default, echo, help, quit, verbose, livtoc, crdl, lidl, dsdl, indl, and dumptlog. tmadmin may be invoked in this mode on any node, including inactive nodes. A node is considered active if tmadmin can join the application as an administrative process or client (via a running BBL). The -r option instructs tmadmin to enter the bulletin board as a client instead of the administrator and provides read-only access. This is useful if it is desired to leave the administrator slot unoccupied. Only one tmadmin process can be the administrator at a time. When the -r option is specified by a user other than the BEA Tuxedo administrator and security is turned on, the user will be prompted for a password. The -v option causes tmadmin to display the BEA Tuxedo version number and license number. After printing out the information, tmadmin exits. If the -v option is entered with either of the other two options, the others are ignored; only the information requested by the -v option is displayed. Normally, tmadmin may be run on any active node within an active application. If it is run on an active node that is partitioned, then commands are limited to read only access to the local bulletin board. These include bbls, bbparms, bbstat, default, dump, dumptlog, echo, help, printclient, printnet, printqueue, printserver, printservice, printtrans, printgroup, reconnect, quit, serverparms, serviceparms, and verbose, in addition to the configuration commands.
If the partitioned node is the backup node for the MASTER (specified as the second entry on the MASTER parameter in the RESOURCES section of the configuration file), the master command is also available to make this node the MASTER for this part of the partitioned application. If the application is inactive, tmadmin can only be run on the MASTER processor. In this mode, all of the configuration mode commands are available plus the TLOG commands (crlog, dslog, and inlog) and boot.
Once tmadmin has been invoked, commands may be entered at the prompt (">") according to the following syntax: command [arguments].
Several commonly occurring arguments can be given defaults via the default command. Commands that accept parameters set via the default command check default to see if a value has been set. If one hasn't, an error message is returned. In a networked or multiprocessor environment, a single bulletin board can be accessed by setting a default machine (the logical machine id (LMID) as listed in the MACHINES section of the UBBCONFIG file). If the default machine is set to all, all bulletin boards are accessed. If machine is set to DBBL, the distinguished bulletin board is addressed. The default machine is shown as part of the prompt, as in: MASTER> .
If the machine is not set via the default command, the DBBL is addressed (the local BBL is used in a SHM configuration). The machine value for a command can generally be obtained from the default setting (printserver is an example). A caution is required here, however, because some commands (the TLOG commands, for example) act on devices found through TUXCONFIG; a default setting of DBBL or all results in an error. There are some commands where the machine value must be provided on the command line (logstart is an example); the value does not appear as an argument to the -m option. Once set, a default remains in effect until the session is ended, unless changed by another default command. Defaults may be overridden by entering an explicit value on the command line, or unset by entering the value "*". The effect of an override lasts for a single instance of the command. Output from tmadmin commands is paginated according to the pagination command in use (see the paginate subcommand below). There are some commands that have either verbose or terse output. The verbose command can be used to set the default output level. However, each command (except boot, shutdown and config) takes a -v or -t option to turn verbose or terse output on for that command only. When output is printed in terse mode, some of the information (for example, LMID or GROUP name, service or server name) may be truncated. This is indicated by a plus sign, +, at the end of the value. The entire value may be seen by re-entering the command in verbose mode.
tmadmin Commands
Commands may be entered either by their full name or their abbreviation (as given in parentheses), followed by any appropriate arguments. Arguments appearing in square brackets, [], are optional; those in curly braces, {}, indicate a selection from mutually exclusive options. Note that command line options that do not appear in square brackets need not appear on the command line (that is, they are optional) if the corresponding default has been set via the default command. Ellipses following a group of options in curly brackets, {}..., indicate that more than one of the options may appear on the command line (at least one must appear).
If groupname is specified (on the command line or by default), abort the transaction associated with the specified transaction index, tranindex, at the specified server group. Otherwise, notify the coordinator of the transaction to abort the global transaction. If the transaction is known to be decided and the decision was to commit, aborttrans will fail. The index is taken from the previous execution of the printtrans command. To completely get rid of a transaction, printtrans and aborttrans must be executed for all groups that are participants in the transaction. This command should be used with care.
The following provides a brief description of tmadmin commands. For a complete description see the online documentation.
Environment Variables
tmadmin acts as an application client if the -r option is used or if it cannot register as the application administrator. If this is the case, then the APP_PW environment variable must be set to the application password in a security application if standard input is not from a terminal.
Diagnostics
If the tmadmin command is entered before the system has been booted, the following message is displayed:
No bulletin board exists. Entering boot mode
>
tmadmin then waits for a boot command to be entered. If the tmadmin command is entered, without the -c option, on an inactive node that is not the MASTER, the following message is displayed and the command terminates:
Cannot enter boot mode on non-master node.
If an incorrect application password is entered or is not available to a shell script through the environment, then a log message is generated, the following message is displayed and the command terminates:
Invalid password entered.
tmboot
Function
Bring up a BEA Tuxedo configuration
Synopsis
tmboot [-l lmid] [-g grpname] [-i srvid] [-s aout] [-o sequence]
[-S] [-A] [-b] [-B lmid] [-T grpname] [-e command] [-w] [-y] [-q] [-n] [-c] [-M] [-d1]
Description
tmboot brings up a BEA Tuxedo application in whole or in part depending on the options specified. tmboot can be invoked only by the administrator of the bulletin board (as indicated by the UID parameter in the configuration file) or by root. tmboot can be invoked only on the machine identified as MASTER in the RESOURCES section of the configuration file, or the backup acting as the MASTER, that is, with the DBBL already running (via the master command in tmadmin). Except, if the -b option is used, the system can be booted from the backup machine without it having been designated as the MASTER. With no options, tmboot executes all administrative processes and all servers listed in the SERVERS section of the configuration file named by the environment variables, TUXCONFIG and TUXOFFSET. If the MODEL is MP, a DBBL administrative server is started on the machine indicated by the MASTER parameter in the RESOURCES section. An administrative server (BBL) is started on every machine listed in the MACHINES section. For each group in the GROUPS section, TMS servers are started based on the TMSNAME and TMSCOUNT parameters for each entry. All administrative servers are started followed by servers in the SERVERS sections. Any TMS or gateway servers for a group are booted before the first application server in the group is booted. The TUXCONFIG file is propagated to remote machines as necessary. tmboot normally waits for a booted process to complete its initialization (that is, tpsvrinit()) before booting the next process. Booting a gateway server implies that the gateway advertises its administrative service, and also advertises the application services representing the foreign services based on the CLOPT parameter for the gateway (-A will cause all services defined when the gateway is built with buildgateway to be advertised; -s can be used to give a list of services). If the instantiation has the concept of foreign servers, these servers are booted by the gateway at this time. Booting an LMID is equivalent to booting all groups on that LMID. Application servers are booted in the order specified by the SEQUENCE parameter, or in the order of server entries in the configuration file (see description in ubbconfig). If two or more servers in the SERVERS section of the configuration file have the same SEQUENCE parameter, then tmboot may boot these servers in parallel and will not continue until they all complete initialization. Each entry in the SERVERS section can have a MIN and MAX parameter. tmboot boots MIN application servers (the default is 1 if MIN is not specified for the server entry) unless the -i option is specified; using the -i option causes individual servers to be booted up to MAX occurrences. If a server can not be started, a diagnostic is written on the central event log (and to the standard output, unless -q is specified), and tmboot continues -- except that if the failing process is a BBL, servers that depend on that BBL are silently ignored; if the failing process is a DBBL, tmboot ignores the rest of the configuration file. If a server is configured with an alternate LMID and fails to start on its primary machine, tmboot automatically attempts to start the server on the alternate machine and, if successful, sends a message to the DBBL to update the server group section of TUXCONFIG. For servers in the SERVERS section, only CLOPT, SEQUENCE, SRVGRP and SRVID are used by tmboot. Collectively, these are known as the server's boot parameters. Once the server has been booted, it reads the configuration file to find its runtime parameters. (See ubbconfig(5) for a description of all parameters.) All administrative and application servers are booted with APPDIR as their current working directory. The value of APPDIR is specified in the configuration file in the MACHINES section for the machine on which the server is being booted. The search path for the server executables is APPDIR, followed by TUXDIR/bin, followed by /bin and /usr/bin, followed by any PATH specified in the ENVFILE for the MACHINE. The search path is only used if an absolute path name is not specified for the server. Values placed in the server's ENVFILE are not used for the search path. When a server is booted, the variables TUXDIR, TUXCONFIG, TUXOFFSET, and APPDIR, with values specified in the configuration file for that machine, are placed in the environment. The environment variable LD_LIBRARY_PATH is also placed in the environment of all servers. Its value defaults to $APPDIR:$TUXDIR/lib:/lib:/usr/lib:lib> where lib> is the value of the first LD_LIBRARY_PATH= line appearing in the machine ENVFILE. See ubbconfig for a description of the syntax and use of the ENVFILE. The ULOGPFX for the server is also set up at boot time based on the parameter for the machine in the configuration file. If not specified, it defaults to $APPDIR/ULOG. All of these operations are performed before the application initialization function, tpsvrinit(), is called. Many of the command line options of tmboot serve to limit the way in which the system is booted and can be used to boot a partial system. The following options are supported:
Environment Variables
During the installation process, an administrative password file is created. When necessary, BEA Tuxedo searches for this file in the following directories (in the order shown): APPDIR/.adm/tlisten.pw TUXDIR/udataobj/tlisten.pw To ensure that your password file will be found, make sure you have set the APPDIR and/or TUXDIR environment variables.
Diagnostics
If TUXCONFIG is set to a non-existent file, two fatal error messages are displayed: error processing configuration file configuration file not found If tmboot fails to boot a server, it will exit with exit code 1 and the user log should be examined for further details; otherwise it will exit with exit code 0. If tmboot is run on an inactive non-master node, a fatal error message is displayed: tmboot cannot run on a non-master node. If tmboot is run on an active node that is not the acting master node, a fatal error message is displayed:
tmboot cannot run on a non acting-master node in an active application.
If the same IPCKEY is used in more than one TUXCONFIG file, tmboot fails with the following message:
Configuration file parameter has been changed since last tmboot
If there are multiple node names in the MACHINES section in a non-LAN configuration, a fatal error message is displayed: Multiple nodes not allowed in MACHINES for non-LAN application.
Examples
To start only those servers located on the machines logically named CS0 and CS1:
tmboot -l CS0 -l CS1
To start only those servers named CREDEB and belonging to group DBG1:
tmboot -g DBG1 -s CREDEB1
To boot a BBL on the machine logically named PE8, as well as all those servers whose location is specified as PE8:
tmboot -B PE8 -l PE8
To view minimum IPC resources needed for the configuration:
tmboot -c
tmloadcf
Function
Parse a UBBCONFIG file and load binary TUXCONFIG configuration file
Synopsis
tmloadcf [-n] [-y] [-c] [-b blocks] {ubbconfig_file | -}Description
tmloadcf reads a file or the standard input that is in UBBCONFIG syntax, checks the syntax, and optionally loads a binary TUXCONFIG configuration file. The TUXCONFIG and (optionally) TUXOFFSET environment variables point to the TUXCONFIG file and (optional) offset where the information should be stored. tmloadcf can only be run on the MASTER machine, as defined in the RESOURCES section of the UBBCONFIG file, unless the -c or -n option is specified. tmloadcf prints a warning message if it finds any section of the UBBCONFIG file missing, other than a missing NETWORK section in a configuration where the LAN OPTION is not specified (see ubbconfig) or a missing ROUTING section. If a syntax error is found while parsing the input file, tmloadcf exits without performing any updates to the TUXCONFIG file. The effective user identifier of the person running tmloadcf must match the UID, if specified, in the RESOURCES section of the UBBCONFIG file. The -c option to tmloadcf causes the program to print minimum IPC resources needed for this configuration. Resource requirements that vary on a per-processor basis are printed for each processor in the configuration. The TUXCONFIG file is not updated. The -n option to tmloadcf causes the program to do only syntax checking of the ASCII UBBCONFIG file without actually updating the TUXCONFIG file. After syntax checking, tmloadcf checks to see if the file pointed to by TUXCONFIG exists, is a valid BEA Tuxedo system file system, and contains TUXCONFIG tables. If these conditions are not true, the user is prompted to decide if they want tmloadcf to create and initialize the file with Initialize TUXCONFIG file: path [y, q]? Prompting is suppressed if the standard input or output are not terminals, or if the -y option is specified on the command line. Any response other than "y" or "Y" will cause tmloadcf to exit without creating the configuration file. If the TUXCONFIG file is not properly initialized, and the user has given the go-ahead, tmloadcf creates the BEA Tuxedo system file system and then creates the TUXCONFIG tables. If the -b option is specified on the command line, its argument is used as the number of blocks for the device when creating the BEA Tuxedo system file system. If the value of the -b option is large enough to hold the new TUXCONFIG tables, tmloadcf will use the specified value to create the new file system; otherwise, tmloadcf will print an error message and exit. If the -b option is not specified, tmloadcf will create a new file system large enough to hold the TUXCONFIG tables. The -b option is ignored if the file system already exists. The -b option is highly recommended if TUXCONFIG is a raw device (that has not been initialized) and should be set to the number of blocks on the raw device. The -b option is not recommended if TUXCONFIG is a regular UNIX file. If the TUXCONFIG file is determined to already have been initialized, tmloadcf ensures that the system described by that TUXCONFIG file is not running. If the system is running, tmloadcf prints an error message and exits. If the system is not running and TUXCONFIG file already exists, tmloadcf will prompt the user to confirm that the file should be overwritten with Really overwrite TUXCONFIG file [y, q]? Prompting is suppressed if the standard input or output are not a terminal or if the -y option is specified on the command line. Any response other than "y" or "Y" will cause tmloadcf to exit without overwriting the file. If the SECURITY parameter is specified in the RESOURCES section of the configuration, then tmloadcf will flush the standard input, turn off terminal echo and prompt the user for an application password as follows:
Enter Application Password?
Reenter Application Password?
The password is limited to 30 characters. The option to load the ASCII UBBCONFIG file via the standard input (rather than a file) cannot be used when the SECURITY parameter is turned on. If the standard input is not a terminal, that is, if the user cannot be prompted for a password (as with a here file, for example), then the environment variable APP_PW is accessed to set the application password. If the environment variable APP_PW is not set with the standard input not a terminal, then tmloadcf will print an error message, generate a log message and fail to load the TUXCONFIG file. Assuming no errors, and if all checks have passed, tmloadcf loads the UBBCONFIG file into the TUXCONFIG file. It will overwrite all existing information found in the TUXCONFIG tables. Note that some values are rounded during the load and may not match when they are unloaded. These include but are not limited to MAXRFT and MAXRTDATA.
Environment Variables
The environment variable APP_PW must be set for applications that have the SECURITY parameter is specified and run tmloadcf with something other than a terminal as the standard input.
Examples
To load a configuration file from UBBCONFIG file BB.shm, initialized the device with 2000 blocks:
tmloadcf -b2000 -y BB.shm
Diagnostics
If an error is detected in the input, the offending line is printed to standard error along with a message indicating the problem. If a syntax error is found in the UBBCONFIG file or the system is currently running, no information is updated in the TUXCONFIG file and tmloadcf exits with exit code 1. If tmloadcf is run by a person whose effective user identifier doesn't match the UID specified in the UBBCONFIG file, the following error message is displayed:
*** UID is not effective user ID ***
If tmloadcf is run on a non-master node, the following error message is displayed:
tmloadcf cannot run on a non-master node.
If tmloadcf is run on an active node, the following error message is displayed:
tmloadcf cannot run on an active node.
Upon successful completion, tmloadcf exits with exit code 0. If the TUXCONFIG file is updated, a userlog message is generated to record this event.
tmshutdown
Function
Shutdown a set of BEA Tuxedo servers
Synopsis
tmshutdown [options]
Description
tmshutdown stops the execution of a set of servers or removes the advertisements of a set of services listed in a configuration file. Only the administrator of the bulletin board (as indicated by the UID parameter in the configuration file) or root can invoke the tmshutdown command. tmshutdown can be invoked only on the machine identified as MASTER in the RESOURCES section of the configuration file, or the backup acting as the MASTER, that is, with the DBBL already running (via the master command in tmadmin). An exception to this is the -P option which is used on partitioned processors (see below). With no options, tmshutdown stops all administrative, TMS, and gateway servers, and servers listed in the SERVERS section of the configuration file named by the TUXCONFIG environment variable and removes their associated IPC resources. For each group, all servers in the SERVERS section, if any, are shutdown followed by any associated gateway servers (for foreign groups) and TMS servers. Administrative servers are shutdown last. Application servers without SEQUENCE parameters are shutdown first in reverse order of the server entries in the configuration file, followed by servers with SEQUENCE parameters that are shutdown from high to low sequence number. If two or more servers in the SERVERS Section of the configuration file have the same SEQUENCE parameter, then tmshutdown may shut down these servers in parallel. Each entry in the SERVERS Section may have an optional MIN and MAX parameter. tmshutdown shuts down all occurrences of a server (up to MAX occurrences) for each server entry, unless the -i option is specified; using the -i option causes individual occurrences to be shut down. If it is not possible to shutdown a server, or remove a service advertisement, a diagnostic is written on the central event log (see userlog). The following is a description of all options:
Note: This option maps to the UNIX signals SIGTERM and SIGKILL on platforms which support them. By default, a SIGTERM initiates orderly shutdown in a BEA Tuxedo server. Application resetting of SIGTERM could cause to be unable to shutdown the server.
Diagnostics
If tmshutdown fails to shut down a server or a fatal error occurs, it will exit with exit code 1 and the user log should be examined for further details; otherwise it will exit with exit code 0. If tmshutdown is run on an active node that is not the acting master node, a fatal error message is displayed:
tmshutdown cannot run on a non acting-master node in an active application.
If shutting down a process would partition active processes from the DBBL, a fatal error message is displayed:
cannot shutdown, causes partitioning.
If a server has died, the following somewhat ambiguous message is produced: CMDTUX_CAT:947
Cannot shutdown server GRPID
Examples
To shutdown the entire system and remove all BEA Tuxedo IPC resources (force it if confirmation not received in 30 seconds):
tmshutdown -w 30
To shutdown only those servers located on the machine with lmid of CS1. Since the -l option restricts the action to servers listed in the SERVERS section, theBBL on CS1 is not shutdown:
tmshutdown -l CS1
ud, ud32, wud, wud32
Function
BEA Tuxedo 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. 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 system. By using flags (see INPUT FORMAT) to begin the lines of the input packet, you can use ud to test BEA Tuxedo 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 Workstation, only the wud and wud32 commands will be present.
Options
ud supports the following options:
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:
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) 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 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).
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 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.
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.
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|