File Formats, Data Descriptions, MIBs, and System Processes Reference
There are two general types of errors that may be returned to the user when interfacing with component MIBs. First, any of the three ATMI verbs (tpcall()
, tpgetrply()
and tpdequeue()
) used to retrieve responses to administrative requests may return any error defined on their respective reference pages.
Second, if the request is successfully routed to a system service capable of satisfying the request and that service determines that there is a problem handling the request, failure may be returned in the form of an application level service failure. In these cases, tpcall()
or tpgetrply()
returns an error with tperrno()
set to TPESVCFAIL
and returns a reply message containing the original request along with TA_ERROR
, TA_STATUS
or TA_BADFLD
fields further qualifying the error as described below. When a service failure occurs for a request forwarded to the system through the TMQFORWARD(5)
server, the failure reply message will be enqueued to the failure queue identified on the original request (assuming the -d
option was specified for TMQFORWARD
).
When a service failure occurs during processing of an administrative request, the FML32 field TA_STATUS
is set to a textual description of the failure, the FML32 field TA_ERROR
is set to indicate the cause of the failure as indicated below. TA_BADFLD
is set as indicated in the description of the individual errors below. All error codes specified below are guaranteed to be negative.
The originating request required application cooperation to be successfully completed and the application did not allow the operation to be completed. For example, server shutdown requires application cooperation.
The configuration file associated with the component MIB could not be accessed as needed to satisfy the requested operation.
An operating system error occurred while attempting to satisfy the request. TA_STATUS
is updated with the translation of the system error code errno
.
An attempt was made to SET
an attribute for which the user does not have write permissions or the user attempted a GET
on a class for which the user does not have read permissions. TA_BADFLD
is set to indicate the field identifier that failed permissions checking.
A SET
operation failed due to a mismatch between the specified pre-image and the current object. TA_BADFLD
is set to indicate the field identifier that failed the pre-image checking.
The administrative request was made in an improper context. TA_STATUS
is populated with additional information.
A BEA Tuxedo system error occurred while attempting to satisfy the request. TA_STATUS
is updated with more information on the error condition.
The following diagnostic codes are returned in TA_ERROR
to indicate successful completion of an administrative request. These codes are guaranteed to be non-negative.
Access to the FML32 interfaces, and therefore to the component MIBs available for administration of a BEA Tuxedo system application, are available on BEA Tuxedo release 4.2.2 and later. The header files and field tables defining generic MIB attributes are available on BEA Tuxedo release 5.0 and later. Interoperability concerns specific to a particular component MIB are discussed in the reference page for that component MIB.
The existing FML32 and ATMI functions necessary to support administrative interaction with BEA Tuxedo system MIBs, as well as the header file and field table defined in this reference page, are available on all supported native and Workstation platforms.
See the "USAGE
" section earlier for some brief example uses of existing APIs in interfacing with generic MIB processing. More detailed examples are provided with each component MIB reference page that make use of real component MIB classes and attributes.
${TUXDIR}/include/tpadm.h
,${TUXDIR}/udataobj/tpadm
tpacall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c), Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), AUTHSVR(5)
, TM_MIB(5)
, TMQFORWARD(5)
Setting Up a BEA Tuxedo Application
Administering a BEA Tuxedo Application at Run Time
Programming a BEA Tuxedo ATMI Application Using C
Programming a BEA Tuxedo ATMI Application Using FML
nl_types
—Native language data types
The nl_types.h
header file contains the following definitions:
Used by nl_langinfo()
to identify items of langinfo()
data. Values for objects of type nl_item
are defined in langinfo.h
.
Used by gencat()
when no $set
directive is specified in a message text source file. This constant can be used in subsequent calls to catgets()
as the value of the set identifier parameter.
gencat(1), catgets(3c), catopen, catclose(3c), nl_langinfo(3c), langinfo(5)
servopts—
Run-time options for server processes
AOUT CLOPT= [-A][-s{@
filename
|service
[,service
...][:func
]}]
[-estderr_file
][-h][-llocktype
][-nprio
]
[-ostdout_file
][-P][-p [L][low_water
][,[terminate_time
]]
[:[high_water
][,create_time
]][-r][-t][ --uargs
][-v]
servopts
is not a command. Rather, it is a list of run-time options recognized by servers in a BEA Tuxedo system.
The server using these options may be one of the BEA Tuxedo system-supplied servers, or it may be an application-supplied server built with the buildserver(1) command.
Running servers in a BEA Tuxedo system is accomplished through the tmboot(1) and tmadmin(1) commands working with servers (and other resources) specified in the application configuration file. Desired selections from the servopts
list are specified with the server in the configuration file. The following options are recognized:
Indicates that the server should initially offer all services with which it was constructed. For BEA Tuxedo system-supplied servers, -A
is the only way of specifying services.
Specifies the names of services to be advertised when the server is booted. 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:
will run the associated server initially offering services x
, y
, and z
, each 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:
runs the associated server with initial services x, y, and z, each processed by the function abc.
Spaces are not allowed between commas. Function name is preceded by a colon. 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(1) or TM_MIB(5)
, only the first 15 characters of a name are displayed.
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 start with `#' or `:'. The -s
option may be specified multiple times.
The run-time association of service name with processing function within a server load module is called the dynamic service capability. The tmadmin
advertise
command can be used to change the list of services offered as the server continues to run.
Service names beginning with the `.' character are reserved for system servers. Application servers specifying such services will fail to boot.
Specifies the name of a file to be opened as the server's standard error file. Providing this option ensures that a restarted server has the same standard error file as its predecessors. If this option is not used, a default diversion file called stderr
is created in the directory specified by $APPDIR
.
Lock the server in core. The argument for locktype
is t
, d
, or p
according to whether the text (TXTLOCK
), data (DATLOCK
), or the entire process (text and data—PROCLOCK
), should be locked. See plock
(2) for details. The lock fails if the server is not run as root. There is no way to unlock a server once it is locked.
nice
the server according to the prio
argument. Giving the process better priority (a negative argument) requires it to be run with the UID
of root
. See nice
(2) for details.
Specifies the name of a file to be opened as the server's standard output file. Providing this option ensures that a restarted server has the same standard output file as its predecessors. If this option is not used, a default diversion file called stdout
is created in the directory specified by $APPDIR
.
SUSP
(suspended) when booting and tpsvrinit
()
is running. Requests to a suspended service will fail and return TPNOENT
immediately. tpsvrinit
()
runs for an extended period of time, the -P
option helps avoid service requests timeout at the booting stage.AVAIL
(available) after tpsvrinit
()
has completed and the server is ready to receive requests. -p
[L
][low_water
][,[terminate_time
]][:[high_water
][,create_time
]]
This option can be used to support the automatic spawning and decaying of servers, both single-threaded RPC servers and conversational servers. For RPC servers, this option must be used on an MSSQ set with MAX greater than 1. For conversational servers, the MAX must be greater than 1.
The decision to spawn/decay servers is based on the number of requests per server on the queue. However, if the load [L
] argument is used with RPC servers, than the load factor of each request is also considered.
If the -p option is specified with the L argument, then, if the load meets or exceeds a threshold (specified by the high_water argument) for a specified amount of time (in seconds), the system will spawn additional servers. If, however, the value of high_water is 1, then the single server responsible for spawning another server will not do so as long as it is handling messages.
This problem will persist as long as there is only one request waiting on the queue: the server will process it once it finishes its current request and it will not need to start a new server.
However, when additional requests start arriving and waiting on the queue, then you should eventually see new servers getting started. Again, the new servers will be started when the currently running server finishes processing the current request and starts checking for the next one.
Every time a server returns to its queue to get a new message to process, it checks the conditions governing the need for new servers. If those conditions are met, the server spawns exactly one new server.
Note: For UNIX platforms only—the alarm()
system call does not work as expected in servers running under server pool management. Because the code that terminates idle servers uses the alarm()
call, user-written code intended to establish a customized signal handler fails to do so, despite the fact that calls to Usignal()
do not result in errors.
Depending on which type of server is being used, arguments to the -p
option have the following meanings:
The load argument works only with RPC servers. It also only works in SHM mode with load balancing turned on. The decision to spawn more servers is based on the request load, rather than the number of messages per server. If SHM/LDBAL=Y
is not set, a user log message (LIBTUX_CAT:1542
) is printed and no spawning or decaying occurs.
These arguments are used to control when RPC servers are spawned or deactivated based on the number of messages per server. If the load exceeds high_water
for at least create_time
seconds, a new server is spawned. If the load drops below low_water
for at least terminate_time
seconds, a server is deactivated. low_water
defaults to an average of 1 message per server on the MSSQ or a workload of 50. high_water
defaults to an average of 2 messages per server, or a workload of 100. create_time
defaults to 50 and terminate_time
defaults to 60.
These arguments are used to control when conversational servers are spawned or deactivated. Since conversational servers typically run for a longer time than RPC servers, a conversational server checks the minimum low_water
percentage and the maximum high_water
percentage of other servers that are currently engaged in conversations. If the percentage exceeds the value set for the related time parameters, terminate_time
and create_time
respectively, a server may be decayed or spawned, provided that the minimum or maximum number of servers has not been reached.
Also, you can specify a value of 0 seconds for the time parameters so that either a spawn or decay action will occur as soon as the server detects that the percentage has been exceeded. low_water
percentage defaults to 0% and the high_water
percentage defaults to 80%. terminate_time
defaults to 60 seconds and create_time
defaults to 0 seconds.
Specifies that the server should record, on its standard error file, a log of services performed. This log may be analyzed by the txrpt(1) command. When the -r
option is used, make sure that the ULOGDEBUG
variable is not set to "y". The ULOGDEBUG
variable prevents debugging messages from being sent to stderr
. Debugging messages in the file will be misinterpreted by txrpt
.
Specifies that the server in this BEA Tuxedo 7.1 or later application is allowed to interoperate with pre-release 7.1 BEA Tuxedo software. The server may be a workstation listener (WSL) process (which when started with the -t
option allows interoperability for all of its workstation handler—WSH—processes), a domain gateway (GWTDOMAIN
) process, or a system or application server process.
Marks the end of system-recognized arguments and the start of arguments to be passed to a subroutine within the server. This option is needed only if the user wishes to supply application-specific arguments to the server. The system-recognized options precede the --
; application arguments should follow it. Application arguments may be processed by a user-supplied version of the tpsvrinit()
function. getopt()
should be used to parse them. Because all system arguments are processed prior to the call to tpsvrinit()
, when the call is made the external integer, optind
points to the start of the user flags. The same option letters (for example, -A
) may be reused after the --
argument, and given any meaning appropriate to the application.
Prints out the service name/function name list to standard output, beginning with the following comment lines:
#
where the first three lines are comments and begin with a pound sign (
# List of services and corresponding handler functions built into the server
#
<servicename>:<functionname><NEWLINE>
<servicename>:<functionname><NEWLINE>
<servicename>:<functionname><NEWLINE>
. . . .
. . . . #
) character. Each following line includes a service name and its corresponding function name built into the executable. The servicename
field on any line can be an empty string if an "-s:
functionname
" is included on the buildserver
command line. The functionname
field is always present.
Note: At run time the BEA Tuxedo system automatically adds the following option to each command line for each server:
The -c
option adds a comment line, in which the specified domain ID is reported, to any command output that reports on the processes associated with the domain in question, such as the output of the ps
command. This comment helps an administrator who is managing multiple domains to interpret a single output stream that refers to several domains.
See the Examples section of UBBCONFIG(5)
.
buildserver(1), tmadmin(1), tmboot(1), txrpt(1), tpsvrinit(3c), UBBCONFIG(5)
Setting Up a BEA Tuxedo Application
Administering a BEA Tuxedo Application at Run Time
nice
(2), plock
(2), getopt
(3) in a UNIX system reference manual
TM_MIB
—Management Information Base for core BEA Tuxedo system
#include <fml32.h>
#include <tpadm.h>
The BEA Tuxedo System MIB defines the set of classes through which the fundamental aspects of an application can be configured and managed. This includes management of machines, servers, networking.
TM_MIB(5)
should be used in combination with the generic MIB reference page MIB(5)
to format administrative requests and interpret administrative replies. Requests formatted as described in MIB(5)
using classes and attributes described in this reference page may be used to request an administrative service using any one of a number of existing ATMI interfaces in an active application. Inactive applications may also be administered using the tpadmcall()
function interface. For additional information pertaining to all TM_MIB(5)
class definitions, see TM_MIB(5) Additional Information.
TM_MIB
(5) consists of the following classes.
Each class description consists of four sections:
OVERVIEW
—high level description of the attributes associated with the class.ATTRIBUTE TABLE
—the format of the attribute table is summarized below and described in detail in MIB(5)
.ATTRIBUTE SEMANTICS
—defines the interpretation of each attribute that is part of the class.LIMITATIONS
—limitations in the access to and interpretation of this class.Each class that is a part of this MIB is defined in four parts in sections that follow. One of the four parts is the attribute table. The attribute table is a reference guide to the attributes within a class and how they may used by administrators, operators, and general users to interface with an application.
There are five columns for each attribute described in an attribute table: name, type, permissions, values, and default. Each of these components is discussed in MIB(5)
.
MIB(5)
defines the generic TA_FLAGS
attribute, which is a long
containing both generic and component MIB specific flag values. The following are the TM_MIB(5)
specific flag values supported. These flag values should be or'd with any generic MIB flags.
A flag used to indicate that only administrative processes should be activated when changing the state of a T_MACHINE
object from INActive
to ACTive
.
A flag used to indicate that only application processes should be considered when activating or deactivating a T_MACHINE
object. It may also be used on T_SERVER
and T_SERVERCTXT
retrievals to restrict the retrieval to application servers only.
A flag used to indicate that only configured groups and servers should be considered in satisfying the request.
The field table for the attributes described in this reference page is found in the file udataobj/tpadm
relative to the root directory of the BEA Tuxedo system software installed on the system. The directory ${TUXDIR}/udataobj
should be included by the application in the colon-separated list specified by the FLDTBLDIR
environment variable, and the field table name tpadm
should be included in the comma-separated list specified by the FIELDTBLS
environment variable.
Access to the header files and field tables for this MIB is being provided only on BEA Tuxedo release 6.1 sites and later, both native and Workstation.
Workstation access to this MIB is limited to run-time only access; the function tpadmcall(3c) is not supported on workstations.
For the purpose of preimage processing (MIB_PREIMAGE
flag bit set), local attributes for classes that have global attributes are not considered. Additionally, indexed fields and the indexes that go with them are not considered, for example, T_TLOG
class, TA_TLOGCOUNT
, TA_TLOGINDEX
, TA_GRPNO
, TA_TLOGDATA
attributes.