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 TM_MIB
(5). First, any of the three ATMI verbs (tpcall()
, tpgetrply()
, and tpdequeue()
) used to retrieve responses to administrative requests may return any error defined for them. These errors should be interpreted as described on the appropriate reference pages.
If, however, 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()
and tpcall()
will return an error with tpgetrply()
set to TPESVCFAIL
and return a reply message containing the original request along with TA_ERROR
, TA_STATUS
, and 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, and the FML32 field TA_ERROR
is set to indicate the cause of the failure as indicated below. All error codes are guaranteed to be negative.
Other error return codes generic to any component MIB are specified in the MIB(5)
reference page. These error codes are guaranteed to be mutually exclusive with any TM_MIB
(5) specific error codes defined here.
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.
Other return codes generic to any component MIB are specified in the MIB(5)
reference page. These return codes are guaranteed to be mutually exclusive with any TM_MIB(5)
specific return codes defined here.
The header files and field tables defined in this reference page are available on BEA Tuxedo release 6.1 and later. Fields defined in these headers and tables will not be changed from release to release. New fields may be added which are not defined on the older release site. Access to the AdminAPI is available from any site with the header files and field tables necessary to build a request.
If sites of differing releases, both greater than or equal to BEA Tuxedo release 6.1, are interoperating, information on the older site is available for access and update as defined in the MIB reference page for that release and may be a subset of the information available in the later release.
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.
This section contains a sequence of code fragments that configure, activate, query, and deactivate a two node application using both tpadmcall()
and tpcall()
. Variable names are used in places where reasonable values for a local environment are required, for example, TUXCONFIG
is a two element array of character pointers with each element identifying the full pathname of the TUXCONFIG
file on that machine.
The field table tpadm
must be available in the environment to have access to attribute field identifiers. This can be done at the shell level as follows:
$ FIELDTBLS=tpadm
$ FLDTBLDIR=${TUXDIR}/udataobj
$ export FIELDTBLS FLDTBLDIR
The following header files are included.
#include <atmi.h>
#include <fml32.h>
#include <tpadm.h>
${TUXDIR}/lib/libtmib.a, ${TUXDIR}/lib/libqm.a,
${TUXDIR}/lib/libtmib.so.<rel>
, ${TUXDIR}/lib/libqm.so.<rel>
,
${TUXDIR}/lib/libtmib.lib
The libraries must be linked manually when using buildclient
. The user must use: -L${TUXDIR}/lib -ltmib -lqm
The following code creates and populates an FML32 buffer that is then passed to tpadmcall()
for processing. This example also shows interpretation of tpadmcall()
return codes. The request shown creates the initial configuration for the application.
/* Allocate and initialize the buffer */
ibuf = (FBFR32 *)tpal loc("FML32", NULL, 4000);
obuf = (FBFR32 *)tpalloc("FML32", NULL, 4000);
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes to be set in T_DOMAIN class object */
Fchg32(ibuf, TA_OPTIONS, 0, "LAN,MIGRATE", 0);
Fchg32(ibuf, TA_IPCKEY, 0, (char *)&ipckey, 0);
Fchg32(ibuf, TA_MASTER, 0, "LMID1", 0);
Fchg32(ibuf, TA_MODEL, 0, "MP", 0);
/* Set TM_MIB(5) attributes for TA_MASTER T_MACHINE class object */
Fchg32(ibuf, TA_LMID, 0, "LMID1", 0);
Fchg32(ibuf, TA_PMID, 0, pmid[0], 0);
Fchg32(ibuf, TA_TUXCONFIG, 0, tuxconfig[0], 0);
Fchg32(ibuf, TA_TUXDIR, 0, tuxdir[0], 0);
Fchg32(ibuf, TA_APPDIR, 0, appdir[0], 0);
Fchg32(ibuf, TA_ENVFILE, 0, envfile[0], 0);
Fchg32(ibuf, TA_ULOGPFX, 0, ulogpfx[0], 0);
Fchg32(ibuf, TA_BRIDGE, 0, "/dev/tcp", 0);
Fchg32(ibuf, TA_NADDR, 0, naddr[0], 0);
Fchg32(ibuf, TA_NLSADDR, 0, nlsaddr[0], 0);
/* Perform the action via tpadmcall() */
if (tpadmcall(ibuf, obuf, 0) 0) {
fprintf(stderr, "tpadmcall failed: %s\n", tpstrerror(tperrno));
/* Additional error case processing */
}
The following code reuses the buffers allocated in the previous section to build a request buffer. The request shown below adds a second machine to the configuration established earlier.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_MACHINE", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes to be set in T_MACHINE class object */
Fchg32(ibuf, TA_LMID, 0, "LMID2", 0);
Fchg32(ibuf, TA_PMID, 0, pmid[1], 0);
Fchg32(ibuf, TA_TUXCONFIG, 0, tuxconfig[1], 0);
Fchg32(ibuf, TA_TUXDIR, 0, tuxdir[1], 0);
Fchg32(ibuf, TA_APPDIR, 0, appdir[1], 0);
Fchg32(ibuf, TA_ENVFILE, 0, envfile[1], 0);
Fchg32(ibuf, TA_ULOGPFX, 0, ulogpfx[1], 0);
Fchg32(ibuf, TA_BRIDGE, 0, "/dev/tcp", 0);
Fchg32(ibuf, TA_NADDR, 0, naddr[1], 0);
Fchg32(ibuf, TA_NLSADDR, 0, nlsaddr[1], 0);
tpadmcall(...) /* See earlier example for detailed error processing */
The existing buffers are again reused to identify the newly configured second machine as the backup master site for this application.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0);
/* Set TM_MIB(5) T_DOMAIN attributes changing *
Fchg32(ibuf, TA_MASTER, 0, "LMID1,LMID2", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
Reuse the buffers to generate two requests, each adding one server group to the configured application. Note how the second request simply modifies the necessary fields in the existing input buffer.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_GROUP", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes defining first group */
Fchg32(ibuf, TA_SRVGRP, 0, "GRP1", 0);
Fchg32(ibuf, TA_GRPNO, 0, (char *)&grpno[0], 0);
Fchg32(ibuf, TA_LMID, 0, "LMID1,LMID2", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
/* Set TM_MIB(5) attributes defining second group */
Fchg32(ibuf, TA_SRVGRP, 0, "GRP2", 0);
Fchg32(ibuf, TA_GRPNO, 0, (char *)&grpno[1], 0);
Fchg32(ibuf, TA_LMID, 0, "LMID2,LMID1", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
Reuse the allocated buffers to add one server per group to the configured application.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_SERVER", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes defining first server */
Fchg32(ibuf, TA_SRVGRP, 0, "GRP1", 0);
Fchg32(ibuf, TA_SRVID, 0, (char *)&srvid[0], 0);
Fchg32(ibuf, TA_SERVERNAME, 0, "ECHO", 0)
tpadmcall(...); /* See earlier example for detailed error processing */
/* Set TM_MIB(5) attributes defining second server */
Fchg32(ibuf, TA_SRVGRP, 0, "GRP2", 0);
Fchg32(ibuf, TA_SRVID, 0, (char *)&srvid[1], 0);
tpadmcall(...); /* See earlier example for detailed error processing */
Add a routing criteria definition. Note that routing criteria may be dynamically added to a running application using a similar operation via the tpcall()
interface.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_ROUTING", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes defining routing criteria */
Fchg32(ibuf, TA_ROUTINGNAME, 0, "ECHOROUTE", 0);
Fchg32(ibuf, TA_BUFTYPE, 0, "FML", 0);
Fchg32(ibuf, TA_FIELD, 0, "LONG_DATA", 0);
Fchg32(ibuf, TA_RANGES, 0, "MIN-100:GRP1,100-MAX:GRP2", 26);
tpadmcall(...); /* See earlier example for detailed error processing */
Define a service object that maps the advertised service name to the routing criteria defined above.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_SERVICE", 0);
Fchg32(ibuf, TA_STATE, 0, "NEW", 0);
/* Set TM_MIB(5) attributes defining service entry */
Fchg32(ibuf, TA_SERVICENAME, 0, "ECHO", 0);
Fchg32(ibuf, TA_ROUTINGNAME, 0, "ECHOROUTE", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
Activate the master site administrative processes (DBBL, BBL, Bridge) by setting the T_DOMAIN
class object state to ACTIVE
.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0);
Fchg32(ibuf, TA_STATE, 0, "ACT", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
Now that the application is active, we need to join the application and make our AdminAPI requests via the tpcall()
interface.
/* Now that the system is active, join it as the administrator */ tpinfo = (TPINIT *)tpalloc("TPINIT", NULL, TPINITNEED(0));
sprintf(tpinfo->usrname, "appadmin");
sprintf(tpinfo->cltname, "tpsysadm");
if (tpinit(tpinfo) < 0) {
fprintf(stderr, "tpinit() failed: %s\n", tpstrerror(tperrno));
/* Additional error case processing */
}
/* Reinitialize buffers as typed buffers */
Finit32(ibuf, Fsizeof32(ibuf));
Finit32(obuf, Fsizeof32(obuf));
Activate the remaining portions of the application. Note that the administrative user may request unsolicited notification messages be sent just before and just after the attempted boot of each server by setting the TMIB_NOTIFY
flag in the TA_FLAGS
attribute of the request. This example shows handling of an error return from tpcall()
.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_MACHINE", 0);
Fchg32(ibuf, TA_STATE, 0, "RAC", 0);
/* Set TM_MIB(5) attributes identifying machine */
Fchg32(ibuf, TA_LMID, 0, "LMID1", 0);
/* Invoke the /AdminAPI and interpret results */
if (tpcall(".TMIB", (char *)ibuf, 0, (char **)&obuf, &olen, 0) < 0) {
fprintf(stderr, "tpcall failed: %s\n", tpstrerror(tperrno));
if (tperrno == TPESVCFAIL) {
Fget32(obuf,TA_ERROR,0,(char *)&ta_error,NULL);
ta_status = Ffind32(obuf, TA_STATUS, 0, NULL);
fprintf(stderr, "Failure: %ld, %s\n",
ta_error, ta_status);
/* Additional error case processing */
}
Generate a query on the status of one of the activated servers.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "GET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_SERVER", 0);
flags = MIB_LOCAL;
Fchg32(ibuf, TA_FLAGS, 0, (char *)&flags, 0);
/* Set TM_MIB(5) attributes identifying machine */
Fchg32(ibuf, TA_SRVGRP, 0, "GRP1", 0);
Fchg32(ibuf, TA_SRVID, 0, (char *)&srvid[0], 0);
tpcall(...); /* See earlier example for detailed error processing */
Deactivate the application by setting the state of each machine to INACTIVE
. Note that the TMIB_NOTIFY
flag could be used with this operation also.
/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));
/* Shutdown Remote Machine First */
/* Set MIB(5) attributes defining request type */
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_MACHINE", 0);
Fchg32(ibuf, TA_LMID, 0, "LMID2", 0);
Fchg32(ibuf, TA_STATE, 0, "INA", 0);
tpcall(....); /* See earlier example for detailed error processing */
/* And now application servers on master machine *
flags = TMIB_APPONLY;
Fchg32(ibuf, TA_FLAGS, 0, (char *)&flags, 0);
Fchg32(ibuf, TA_LMID, 0, "LMID1", 0);
tpcall(...); /* See earlier example for detailed error processing */
/* Terminate active application access */
tpterm();
/* Finally, shutdown the master admin processes */
Finit32(ibuf, Fsizeof32(ibuf));
Fchg32(ibuf, TA_OPERATION, 0, "SET", 0);
Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0);
Fchg32(ibuf, TA_STATE, 0, "INA", 0);
tpadmcall(...); /* See earlier example for detailed error processing */
${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), MIB(5)
, WS_MIB(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
Server that runs the FactoryFinder and supporting NameManager services.
TMFFNAME SRVGRP="
identifier
" SRVID="
number
"
[CLOPT="[-A] [servopts options
]
[-- [-F ] [-N | -N -M [-f filename
]]]"]
TMFFNAME
is a server provided by BEA Tuxedo that runs the FactoryFinder and supporting NameManager services which maintain a mapping of application-supplied names to object references.
The FactoryFinder service is a CORBA-derived service that provides client applications with the ability to find application factories that correspond to application-specified search criteria. Consult the BEA Tuxedo CORBA Programming Reference for a complete description on the FactoryFinder API and Creating CORBA Server Applications for a description of registering and unregistering factories. The FactoryFinder service is the "default" service if no services are specified in the CLOPT.
The NameManager service is a BEA Tuxedo-specific service that maintains a mapping of application-supplied names to object references. One usage of this service is to maintain the application factory name-to-object reference list. The NameManager service can be booted with an -M
option that designates a Master role. If the -M
option is not specified, the NameManager is assumed to be a Slave. Slave NameManagers obtain updates from the Master. Only one Master NameManager can be specified in an application.
The master NameManager can be configured to make factory objects residing in remote domains accessible in the local domain. It can also be configured to make factory objects residing in the local domain accessible from remote domains. Either or both of these configuration options can be specified in the FactoryFinder Domains configuration file, factory_finder.ini
.
The location of the factory_finder.ini
file is specified with the -f
command-line option for the master NameManager. If the -f
option is specified and the factory_finder.ini
file is not found, the initialization of the master NameManager fails. If the -f
option is not specified, only locally registered factory objects are accessible to the local application, and none of the local factory objects are accessible to applications in remote domains.
Note: It is possible to boot one or more TMFFNAME
processes running the same service. To provide increased reliability, at least two NameManager services must be configured, preferably on different machines.
The TMFFNAME
servers run on BEA Tuxedo version 4.0 software and later.
If there are less than two NameManager services configured in the application's UBBCONFIG
(TMFFNAME -N
), the server terminates itself during boot and writes an error message to the user log.
If a Master NameManager service is not configured in the application's UBBCONFIG
file and is running when a Slave NameManager service starts, the server terminates itself during boot and writes an error message to the user log. Additionally, if the Master is down, registration and unregistration of factories is disabled until the Master restarts.
If a TMSYSEVT
server is not configured in the application's UBBCONFIG
file and is not running when a NameManager service is being started, the server terminates itself during boot and writes an error message to the user log.
If a NameManager service is not configured in the application's UBBCONFIG
file and a FactoryFinder service is being started, the server terminates itself during boot and writes an error message to the user log.
If running an MP configuration, all name managers (TMFFNAME -N
) should configured to boot before any slave event service servers(TMSYSEVT -S
). The master TMSYSEVT
must still be booted before any name managers. If slave TMSYSEVT
booted before name managers, a slave name manager could miss update events sent by the master name manager, this can result in some clients seeing NoFactory exceptions when trying to find a factory, or the factory finder returning a factory object which is no longer registered (resulting in NO_IMPLEMENT
or other exceptions when invoked on), or unexpected load balancing behavior.
If a slave name manager was shutdown and boot again, and if any customer written CORBA servers that register (or unregister) a factory are booting (or shutting down), then either boot (or shutdown) the customer written servers first or wait for the longest polling interval set on all the slave TMSYSEVT
's. Default for those with no -p
option is 30 seconds.
*SERVERS
TMSYSEVT SRVGRP=ADMIN1 SRVID=44 RESTART=Y
CLOPT="-A"
TMFFNAME SRVGRP=ADMIN1 SRVID=45 RESTART=Y
CLOPT="-A -- -F"
TMFFNAME SRVGRP=ADMIN1 SRVID=46 RESTART=Y
CLOPT="-A -- -N -M -f c:\appdir\import_factories.ini"
TMFFNAME SRVGRP=ADMIN2 SRVID=47 RESTART=Y
CLOPT="-A -- -N"
TMFFNAME SRVGRP=ADMIN3 SRVID=48 RESTART=Y
CLOPT="-A -- -F"
TMFFNAME SRVGRP=ADMIN4 SRVID=49 RESTART=Y
CLOPT="-A -- -F"
factory_finder.ini(5)
, TMSYSEVT(5)
, UBBCONFIG(5)
, userlog(3c), TP Framework in BEA Tuxedo CORBA Programming Reference.
The Interface Repository server
TMIFRSVR SRVGRP="
identifier
" SRVID="
number
" RESTART=Y GRACE=0 CLOPT="[servopts
options
] -- [-f
repository_file_name
]"
The TMIFRSVR
server is a server provided by BEA for accessing the Interface Repository. The API is a subset of the CORBA-defined Interface Repository API. For a description of the Interface Repository API, see BEA Tuxedo CORBA Programming Reference.
Interface Repository filename. This file must have been generated previously using the idl2ir
command. If this parameter is not specified, the default repository filename repository.ifr
located in the application directory (APPDIR
) for the machine is used. If the repository file cannot be read, the server fails to boot.
#This server uses the default repository TMIFRSVR
SRVGRP="IFRGRP" SRVID=1000 RESTART=Y GRACE=0
#This server uses a non-default repository TMIFRSVR
SRVGRP="IFRGRP" SRVID=1001 RESTART=Y GRACE=0
CLOPT="-- -f /nfs/repository.ifr"
ir2idl(1)
, UBBCONFIG(5)
, servopts(5)
TMMETADATA
- Tuxedo service metadata repository server
TMMETADATA SRVGRP
="identifier" SRVID
="number"
CLOPT=
"[-A
] [servopts
options] -- -f
repository_file [-r
]
TMMETADATA is a Tuxedo system server that processes requests to retrieve and/or update Tuxedo service metadata repository information.
TMMETADATA provides and supports just one service, .TMMETAREPOS
, which uses FML32
input and output buffers similar to those used by the Tuxedo MIB. The TMMETADATA FML32
buffer format is described in MIB(5)
.
Note: Metadata information retrieval and updating are handled through a service independent from .TMIB
in order to avoid burdening the BBL with metadata request processing overhead since the metadata repository is stored separately from the Tuxedo configuration.
The CLOPT
option is a string of command link options that is passed to TMMETADATA when it is booted. The following run-time parameters are recognized by TMMETADATA:
Because TMMETADATA provides only one service, .TMMETAREPOS
, multiple TMMETADATA servers running on a particular Tuxedo domain must all be configured for the same permission access. That is, they either should all be read only or they should all be read and write.
Each TMMETADATA server must be configured to access the same metadata repository file or an exact copy of the file to provide consistent request results. Therefore, it is strongly recommended that a stable version of the metadata repository is made available for multiple TMMETADATA server access.
TMMETADATA must run on a Tuxedo 9.0 release or later.
If invoked on a Tuxedo Jolt repository file with the -r option, TMMETADATA can read and return records from that file just as it would for a Tuxedo metadata repository file.
If invoked on a Tuxedo Jolt repository file without the -r option, TMMETADATA fails upon server initialization.
Listing 4 Single TMMETADATA Server Configuration
*SERVERS
TMMETADATA SRVGRP=ADMIN1 SRVID=137 RESTART=Y MAXGEN=5
GRACE=3600 CLOPT="-A -- -f /usr/tuxadmin/METAREPOS"
Listing 5 Multiple TMMETADATA Server Configuration
*SERVERS
TMMETADATA SVRGRP=ADMIN1 SVRID=101 RESTART=N
CLOPT="-A -- -f /usr/tuxadmin/metarepos1 -r"
TMMETADATA SVRGRP=ADMIN1 SVRID=102 RESTART=Y MAXGEN=5
GRACE=3600 CLOPT="-A -- -f /usr/tuxadmin/metarepos1 -r"
TMMETADATA SVRGRP=ADMIN1 SVRID=103 RESTART=Y MAXGEN=5
GRACE=3600 CLOPT="-A -- -f /usr/tuxadmin/metarepos1 -r"
tpgetrepos(3c), tpsetrepos(3c), MIB(5)
.
TMQFORWARD
—Message Forwarding server
TMQFORWARD
SRVGRP
="identifier
"SRVID
="number
"REPLYQ=N
CLOPT="
[-A
] [servopts
options
]--
-q
queuename[,queuename
...]
[-t
trantime
] [-i
idletime
] [-b
timeout
] [-e
] [-d
] [-n
] [-f
delay
] "
The message forwarding server is a BEA Tuxedo system-supplied server that forwards messages that have been stored using tpenqueue()
for later processing. The application administrator enables automated message processing for the application servers by specifying this server as an application server in the SERVERS
section.
The location, server group, server identifier and other generic server related parameters are associated with the server using the already defined configuration file mechanisms for servers. The following is a list of additional command-line options that are available for customization.
Used to specify the names of one or more queues/services for which this server forwards messages. Queue and service names are strings limited to 15 characters. This option is required.
Used to indicate the transaction timeout value used on tpbegin()
for transactions that dequeue messages and forward them to application servers. If not specified, the default is 60 seconds.
Used to indicate the amount of time (in seconds) that the server remains idle after draining the queue(s) that it is reading. A negative value indicates an amount of time in milliseconds. For example if you specify -i -10, the idletime will be 10 milliseconds.
If a value of zero is specified, the server will read the queue(s) continually, which can be inefficient if the queues do not continually have messages. If no value is specified, the default is 30 seconds.
Used to limit nontransaction block waiting time, in seconds, for a forwarded service to complete. The -b
option can only be used with the -f
option.
Used to cause the server to exit if it finds no messages on the queue(s). This, combined with the threshold command associated with the queue(s), can be used to start and stop the TMQFORWARD
server in response to fluctuations of messages that are enqueued.
Used to cause messages that result in service failure and have a reply message (non-zero in length) to be deleted from the queue after the transaction is rolled back. That is, the original request message is deleted from the queue—not put back on the queue—if the service fails and a reply message (non-zero in length) is received from the server.
The reply message is enqueued to the failure queue, if one is associated with the message and the queue exists. If the message is to be deleted at the same time as the retry limit configured for the queue is reached, the original request message is put into the error queue.
Used to cause messages to be sent using the TPNOTRAN
flag. This flag allows for forwarding to server groups that are not associated with a resource manager.
Used to cause the server to forward the message to the service instead of using tpcall
. The message is sent such that a reply is not expected from the service. The TMQFORWARD
server does not block waiting for the reply from the service and can continue processing the next message from the queue. To throttle the system such that TMQFORWARD
does not flood the system with requests, the delay
numeric value can be used to indicate a delay, in seconds, between processing requests; use zero for no delay.
Messages are sent to a server providing a service whose name matches the queue name from which the message is read. The message priority is the priority specified when the message is enqueued, if set. Otherwise, the priority is the priority for the service, as defined in the configuration file, or the default (50).
Messages are dequeued and sent to the server within a transaction. If the service succeeds, the transaction is committed and the message is deleted from the queue. If the message is associated with a reply queue, any reply from the service is enqueued to the reply queue, along with the returned tpurcode
. If the reply queue does not exist, the reply is dropped.
An application may be able to specify the quality of service for a reply to a message when the original message is enqueued. If a reply quality of service is not specified, the default delivery policy specified for the reply queue is used. Note that the default delivery policy is determined when the reply to a message is enqueued. That is, if the default delivery policy of the reply queue is modified between the time that the original message is enqueued and the reply to the message is enqueued, the policy used is the one in effect when the reply is finally enqueued.
If the service fails, the transaction is rolled back and the message is put back on the queue, up to the number of times specified by the retry limit configured for the queue. When a message is put back on the queue, the rules for ordering and dequeuing that applied when it was first put on the queue are (in effect) suspended for delay
seconds; this opens up the possibility, for example, that a message of a lower priority may be dequeued ahead of the restored message on a queue ordered by priority.
If the -d
option is specified, the message is deleted from the queue if the service fails and a reply message is received from the server, and the reply message (and associated tpurcode
) are enqueued to the failure queue, if one is associated with the message and the queue exists. If the message is to be deleted at the same time as the retry limit for the queue is reached, the original request message is put into the error queue.
Any configuration condition that prevents TMQFORWARD
from dequeuing or forwarding messages will cause the server to fail to boot. These conditions include the following:
SRVGRP
must have TMSNAME
set to TMS_QM.
OPENINFO
must be set to indicate the associated device and queue name. SERVER
entry must not be part of an MSSQ set.REPLYQ
must be set to N
. -q
option must be specified in the command-line options. -s
option must not be specified).As delivered, TMQFORWARD
handles the standard buffer types provided with the BEA Tuxedo system. If additional application buffer types are needed, a customized version of TMQFORWARD
needs to be built using buildserver(1) with a customized type switch. See the description in Using the ATMI /Q Component.
The files included by the caller should include only the application buffer type switch and any required supporting routines. buildserver
is used to combine the server object file, $TUXDIR/lib/TMQFORWARD.o
, with the application type switch file(s), and link it with the needed BEA Tuxedo system libraries. The following example provides a sample for further discussion.
buildserver -v -o TMQFORWARD -r TUXEDO/QM -f ${TUXDIR}/lib/TMQFORWARD.o -f apptypsw.o
The buildserver
options are as follows:
Specifies that buildserver
should work in verbose mode. In particular, it writes the cc
command to its standard output.
Specifies the filename of the output load module. The name specified here must also be specified in the SERVERS
section of the configuration file. It is recommended that the name TMQFORWARD
be used for consistency. The application specific version of the command can be installed in $APPDIR
it is booted instead of the version in $TUXDIR/bin
.
Specifies the resource manager associated with this server. The value TUXEDO/QM
appears in the resource manager table located in $TUXDIR/udataobj/RM
and includes the library for the BEA Tuxedo system queue manager.
Specifies the object file that contains the TMQFORWARD
service and should be specified as the first argument to the -f
option.
Specifies one or more user files to be included in the compilation and/or link edit phases of buildserver
. Source files are compiled using the either the cc
command or the compilation command specified through the CC environment variable. These files must be specified after including the TMQFORWARD
.o object file. If more than one file is specified, filenames must be separated by white space (space or tab) and the entire list must be enclosed in quotation marks. This option can be specified multiple times.
The -s
option must not be specified to advertise services.
TMQFORWARD
is supported as a BEA Tuxedo system-supplied server on all supported server platforms.
TMQFORWARD
may be run in an interoperating application, but it must run on a BEA Tuxedo release 4.2 or later node.
*GROUPS # For Windows, :myqueue becomes ;myqueue
TMQUEUEGRP LMID=lmid GRPNO=1 TMSNAME=TMS_QM
OPENINFO="TUXEDO/QM:/dev/device:myqueue"
# no CLOSEINFO is required
*SERVERS # recommended values RESTART=Y GRACE=0
TMQFORWARD SRVGRP="TMQUEUEGRP" SRVID=1001 RESTART=Y GRACE=0
CLOPT=" -- -qservice1,service2" REPLYQ=N
TMQUEUE SRVGRP="TMQUEUEGRP" SRVID=1000 RESTART=Y GRACE=0
CLOPT="-s ACCOUNTING:TMQUEUE"
buildserver(1), tpdequeue(3c), tpenqueue(3c), servopts(5)
, TMQUEUE(5)
, UBBCONFIG(5)
Setting Up a BEA Tuxedo Application
Programming a BEA Tuxedo ATMI Application Using C
TMQUEUE
identifier
SRVGRP=""
number
SRVID="" CLOPT=" [-A][servopts
options] -- [-t
timeout]"
The message queue manager is a BEA Tuxedo system-supplied server that enqueues and dequeues messages on behalf of programs calling tpenqueue()
and tpdequeue()
, respectively. The application administrator enables message enqueuing and dequeuing for the application by specifying this server as an application server in the SERVERS
section.
The location, server group, server identifier and other generic server related parameters are associated with the server using the already defined configuration file mechanisms for servers. The following additional command-line option is available for customization.
Used to indicate the timeout to be used for queuing operations when not in transaction mode (for example, tpenqueue()
or tpdequeue()
are called when the caller is not in transaction mode or with the TPNOTRAN
flag). This value also has an impact on dequeue requests with the TPQWAIT
option since the operation will timeout and an error will be sent back to the requester based on this value. If not specified, the default is 30 seconds.
A TMQUEUE
server is booted as part of an application to facilitate application access to its associated queue space; a queue space is a collection of queues.
Any configuration condition that prevents the TMQUEUE
from enqueuing or dequeuing messages will cause the TMQUEUE
to fail at boot time. The SRVGRP
must have TMSNAME
set to TMS_QM
, and must have OPENINFO
set to indicate the associated device and queue space name.
The tpenqueue()
and tpdequeue()
functions take a queue space name as their first argument. This name must be the name of a service advertised by TMQUEUE
. By default, TMQUEUE
only offers the service "TMQUEUE
". While this may be sufficient for applications with only a single queue space, applications with multiple queue spaces may need to have different queue space names. Additionally, applications may wish to provide more descriptive service names that match the queue space names. Advertising additional service names can be done using the standard server command line option, -s
, as shown below in EXAMPLES
. An alternative is to hard-code the service when generating a custom TMQUEUE
program, as discussed in the following section.
While these methods (the server command line option or a customized server) may be used for static routing of messages to a queue space, dynamic routing may be accomplished using data-dependent routing. In this case, each TMQUEUE
server would advertise the same service name(s) but a ROUTING
field in the configuration file would be used to specify routing criteria based on the application data in the queued message. The routing function returns a GROUP
based on the service name and application typed buffer data, which is used to direct the message to the service at the specified group (note that there can be only one queue space per GROUP
, based on the OPENINFO
string).
As delivered, TMQUEUE
handles the standard buffer types provided with BEA Tuxedo system. If additional application buffer types are needed, a customized version of TMQUEUE
needs to be built using buildserver(1). See the description in Using the ATMI /Q Component.
The customization described in buildserver
can also be used to hard-code service names for the server.
The files included by the caller should include only the application buffer type switch and any required supporting routines. buildserver
is used to combine the server object file, $TUXDIR/lib/TMQUEUE.o
, with the application type switch file(s), and link it with the needed BEA Tuxedo system libraries. The following example provides a sample for further discussion.
buildserver -v -o TMQUEUE -s
qspacename:TMQUEUE -r TUXEDO/QM \
-f ${TUXDIR}/lib/TMQUEUE.o -f apptypsw.o
The buildserver
options are as follows:
Specifies that buildserver
should work in verbose mode. In particular, it writes the cc
command to its standard output.
Specifies the filename of the output load module. The name specified here must also be specified in the SERVERS
section of the configuration file. It is recommended that TMQUEUE
be used for consistency.
Specifies the names of services that can be advertised when the server is booted (see servopts(5)
). For this server, they will be used as the aliases for the queue space name to which requests may be submitted. Spaces are not allowed between commas. The function name, TMQUEUE
, is preceded by a colon. The -s
option may appear several times.
Specifies the resource manager associated with this server. The value TUXEDO/QM
appears in the resource manager table located in $TUXDIR/udataobj/RM
and includes the library for the BEA Tuxedo system queue manager.
Specifies the object file that contains the TMQUEUE
service and should be specified as the first argument to the -f
option.
Specifies one or more user files to be included in the compilation and/or link edit phases of buildserver
. Source files are compiled using the either the cc
command or the compilation command specified through the CC environment variable. These files must be specified after including the TMQUEUE.o
object file. If more than one file is specified, filenames must be separated by white space (space or tab) and the entire list must be enclosed in quotation marks. This option can be specified multiple times.
TMQUEUE
is supported as a BEA Tuxedo system-supplied server on all supported server platforms.
TMQUEUE
may be run in an interoperating application, but it must run on a BEA Tuxedo release 4.2 or later node.
*GROUPS
# For Windows, :myqueue becomes ;myqueue
TMQUEUEGRP1 GRPNO=1 TMSNAME=TMS_QM
OPENINFO="TUXEDO/QM:/dev/device1:myqueue"
# For Windows, :myqueue becomes ;myqueue
TMQUEUEGRP2 GRPNO=2 TMSNAME=TMS_QM
OPENINFO="TUXEDO/QM:/dev/device2:myqueue"
*SERVERS
# The queue space name, myqueue, is aliased as ACCOUNTING in this example
TMQUEUE SRVGRP="TMQUEUEGRP1" SRVID=1000 RESTART=Y GRACE=0
CLOPT="-s ACCOUNTING:TMQUEUE"
TMQUEUE SRVGRP="TMQUEUEGRP2" SRVID=1000 RESTART=Y GRACE=0
CLOPT="-s ACCOUNTING:TMQUEUE"
TMQFORWARD SRVGRP="TMQUEUEGRP1" SRVID=1001 RESTART=Y GRACE=0 REPLYQ=N
CLOPT=" -- -qservice1"
TMQFORWARD SRVGRP="TMQUEUEGRP2" SRVID=1001 RESTART=Y GRACE=0 REPLYQ=N
CLOPT=" -- -qservice1"
*SERVICES
ACCOUNTING ROUTING="MYROUTING"
*ROUTING
MYROUTING FIELD=ACCOUNT BUFTYPE="FML"
RANGES="MIN - 60000:TMQUEUEGRP1,60001-MAX:TMQUEUEGRP2"
In this example, two queues spaces are available. Both TMQUEUE
servers offer the same services and routing is done via the ACCOUNT
field in the application typed buffer.
buildserver(1), tpdequeue(3c), tpenqueue(3c), servopts(5)
, TMQFORWARD(5)
, UBBCONFIG(5)
Setting Up a BEA Tuxedo Application
Administering a BEA Tuxedo Application at Run Time
Programming a BEA Tuxedo ATMI Application Using C
TMSYSEVT
—System event reporting process
TMSYSEVT SRVGRP="
identifier
" SRVID="
number
"
[CLOPT="[-A] [servoptsoptions
]
[-- [-S] [-ppoll-seconds
] [-f
control-file
]]"]
TMSYSEVT
is a BEA Tuxedo system provided server that processes event reports related to system failure or potential failure conditions. The event reports are filtered, and may trigger one or more notification actions.
Filtering and notification rules are stored in control-file
, which defaults to ${APPDIR}/tmsysevt.dat
. Control file syntax is defined in EVENT_MIB(5)
; specifically, the attributes of the classes in EVENT_MIB
can be set to activate subscriptions under the full range of notification rules.
It is possible to boot one or more secondary TMSYSEVT
processes for increased availability. Additional servers must be booted with the -S
command-line option, which indicates a "secondary" server.
When the EVENT_MIB(5)
configuration is updated, the primary TMSYSEVT
server writes to its control file. Secondary servers poll the primary server for changes and update their local control file if necessary. The polling interval is controlled by the -p
option, and is 30 seconds by default.
Note: If you are setting up an MP configuration that includes more than one release of the BEA Tuxedo system and you want to run the TMUSREVT and/or TMSYSEVT server, you must run these servers on the node with the highest available release of the system.
TMSYSEVT
must run on a BEA Tuxedo release 6.0 or later machine.
To migrate the primary TMSYSEVT
server to another machine, the system administrator must provide a current copy of control-file
. Each secondary TMSYSEVT
server automatically maintains a recent copy.
TMSYSEVT
needs access to the system's FML32 field table definitions for system events. FLDTBLDIR32
should include $TUXDIR/udataobj
, and FIELDTBLS32
should include evt_mib
. These environment variables may be set in the machine's or server's environment file.
*SERVERS
TMSYSEVT SRVGRP=ADMIN1 SRVID=100 RESTART=Y GRACE=900 MAXGEN=5
CLOPT="-A --"
TMSYSEVT SRVGRP=ADMIN2 SRVID=100 RESTART=Y GRACE=900 MAXGEN=5
CLOPT="-A -- -S -p 90"
tpsubscribe(3c), EVENTS(5)
, EVENT_MIB(5)
, TMUSREVT(5)
tmtrace
—Run-time tracing facility
The run-time tracing facility allows application administrators and developers to trace the execution of a BEA Tuxedo application.
Run-time tracing is based on the notion of a trace point
, which marks an interesting condition or transition during the execution of an application. Examples of trace points are the entry to an ATMI function such as tpcall
, the arrival of a BEA Tuxedo message, or the start of a transaction.
When a trace point is reached, the following things happen. First, a filter
is applied to determine if the trace point is of interest. If so, a trace record
is emitted to a receiver
, which is a file or (in the future) a buffer. Finally, an action
is triggered, such as aborting the process. Both the emission to a receiver and the trigger are optional, and neither takes place if the trace point does not pass the filter.
The filter, receiver, and trigger are specified in the trace specification
, whose syntax is described below. The trace specification is initialized from the TMTRACE
environment variable. The trace specification of a running process may be changed either as a trigger action or by using the changetrace
command of tmadmin(1).
Trace points are classified into trace categories
, enumerated below. Each trace point belongs to a single category. The filter describes the trace categories of interest, and minimal processing occurs for trace points that do not pass the filter.
Run-time tracing also provides the capability to dye
the messages sent by a client to a server, and transitively by that server to other servers. If a process chooses to dye its messages, the dye is automatically passed by the originating process to all processes that directly or indirectly receive messages from the originating process. When a process receives a dyed message, it automatically turns on the atmi
trace category and starts emitting trace records to the user log, if this was not being done already.
Dyeing can be explicitly turned on or off by the dye
and undye
triggers in the trace specification. Dyeing is also implicitly turned on when a dyed message is received, and implicitly turned off by tpreturn()
and tpforward()
. When it is implicitly turned off, the tracing specification in effect when dyeing was turned on is restored.
Trace points for explicit application calls to the ATMI and TX interfaces, that is, calls to the tp
and tx_
functions, and the invocation of application services There are a few exceptions. Implicit calls are printed in this category where some TX interfaces directly call ATMI interfaces, for the implicit call to tpinit
when an ATMI call is done with first calling tpinit()
, and for cases where tpreturn
is called on error (to aid in debugging).
Trace points for I
mplicit calls to the ATMI and TX interface. These trace points indicate all internal calls made while processing application requests and for administration. Setting this level implies the atmi
level, that is, every call to an ATMI or TX interface is traced (both explicit and implicit).
The trace specification is a string with the syntax filter-spec
:
receiver-spec
[ :
trigger-spec
] where filter-spec
describes the trace categories to be examined or ignored, receiver-spec
is the receiver of trace records, and the optional trigger-spec
describes the action to be performed.
The NULL string is also a legal trace specification. It is the default for all BEA Tuxedo processes if no other specification is supplied.
The strings on
and off
are also accepted: on
is an alias for atmi:ulog:dye
, and off
is equivalent to: :undye
.
The filter specification, which is the first component of the trace specification, has the syntax:
[ { +
| -
} ] [ category
] ...
where category
is one of the categories listed above. The symbol *
can be used in place of category
to denote all categories. The prefix +
or -
specifies that the following category is to be added or subtracted from the set of categories currently in effect. If no category follows a +
or -
, the categories currently in effect are not modified.
An empty filter means that no categories are to be selected, which effectively disables tracing.
When a trace point occurs, its category is compared with the filter specification. If the category is included, the trace point is processed further—according to the receiver and trigger specifications. If the category is not included, no further processing of the trace point occurs.
A receiver is the entity to which a trace record is sent. There is at most one receiver of each trace record.
The receiver specification, which is the second component of the trace specification, has the syntax
[/
regular-expression
/
] receiver
where the optional regular expression may be used to select a subset of the trace points that pass the filter. The regular expression is matched with the trace record. An empty receiver specification is also legal, in which case no trace records are emitted.
A trigger is an optional action performed after a trace record is emitted. At most one action is executed for each trace record that passes the filter.
The trigger specification, which is the optional third part of the trace specification, has the syntax:
[/ regular-expression
/] action
where the optional regular expression may be used to restrict the trigger so that it is executed only for a subset of the trace points that pass the filter. The regular expression is matched with the trace record.
Execute the command
using system
(3) (this is not supported for Windows clients); occurrences of %A are expanded to the value of trace record.
A trace record is a string with the format:
where cc
is the first two characters of the trace category and data
contains additional information about the trace point.
When a trace record appears in the user log, the line looks like this:
hhmmss.system-name
!
process-name.pid
: TRACE:
cc
:
data
Match patterns cannot be specified for the receiver and trigger for Workstation clients running on MAC platforms; the regular expressions will be ignored.
The tmadmin changetrace
command cannot be used to affect the tracing level for Workstation clients.
To trace a client, as well as to trace all ATMI calls made by an application server on behalf of that client, set and export TMTRACE=on
in the environment of the client. This specification will cause all explicit ATMI trace points in the client to be logged and message dyeing to be turned on. Any application server process that performs a service on behalf of the client will automatically log all explicit ATMI trace points.
To see all client trace points, both explicit and implicit, for the previous example, set and export:
TMTRACE="*:ulog:dye:"
To trace service requests from a client as in the previous example, but restrict the tracing output from the client to the bare minimum of information about tpcall
requests, set and export:
TMTRACE=atmi:/tpacall/ulog:dye
in the environment of the client. This specification will cause all tpacall
invocations in the client to be logged and message dyeing to be turned on. Any application server process that performs a service on behalf of the client will automatically log all ATMI trace points. The client's identifier, which is included in the tpacall()
trace record, can be correlated with the value of the TPSVCINFO
parameter passed to any service routine invoked on the client's behalf.
To trace the invocations of all service requests performed by application servers, set:
TMTRACE=atmi:/tpservice/ulog
in the server ENVFILE
s on all participating machines.
To enable run-time tracing of all trace categories throughout an application, with message dyeing turned on, set and export:
TMTRACE=*:ulog:dye
in the environment of all clients and in the machine ENVFILE
s on all participating machines. This setting will probably produce an unmanageable amount of output because all processes, including the BBL
and DBBL
, will emit trace records.
To turn on ATMI tracing in all running servers in group GROUP1
after they are booted, invoke the changetrace
command of tmadmin
as follows:
changetrace -g GROUP1 on
Note that changetrace
affects only currently-existing processes; it does not change the trace configuration of servers in group GROUP1
that have not yet been booted. (To set the default trace configuration of a server, set TMTRACE
in its ENVFILE
.)
To turn off tracing in all currently-running application processes, use changetrace
as follows:
changetrace -m all off
To cause the running server process whose identifier is 1 in group GROUP1
to abort when it executes tpreturn
, specify the following to tmadmin
:
changetrace -i 1 -g GROUP1 "atmi::/tpreturn/abort"
tmadmin(1), userlog(3c), tputrace(3c)
TMUSREVT
—User event reporting process
TMUSREVT SRVGRP="
identifier" SRVID="
number"
options
[CLOPT="[-A] [servopts]
poll-seconds
[-- [-S] [-p] [-f
control-file]]"]
TMUSREVT
is a BEA Tuxedo system provided server that processes event report message buffers from tppost(3c), and acts as an EventBroker to filter and distribute them.
Filtering and notification rules are stored in control-file
, which defaults to ${APPDIR}/tmusrevt.dat
. Control file syntax is defined in EVENT_MIB(5)
; specifically, the attributes of the classes in EVENT_MIB
can be set to activate subscriptions under the full range of notification rules.
It is possible to boot one or more secondary TMUSREVT
processes for increased availability. Additional servers must be booted with the -S
command-line option, which indicates a "secondary" server.
When the EVENT_MIB(5)
configuration is updated, the primary TMUSREVT
server writes to its control file. Secondary servers poll the primary server for changes and update their local control file if necessary. The polling interval is controlled by the -p
option, and is 30 seconds by default.
Note: If you are setting up an MP configuration that includes more than one release of the BEA Tuxedo system and you want to run the TMUSREVT and/or TMSYSEVT server, you must run these servers on the node with the highest available release of the system.
TMUSREVT
must run on a BEA Tuxedo release 6.0 or later machine.
To migrate the primary TMUSREVT
server to another machine, the system administrator must provide a current copy of control-file
. Each secondary TMUSREVT
server automatically maintains a recent copy.
If tppost()
will be called in transaction mode, all TMUSREVT
server groups must have transactional capability (a TMS process).
The TMUSREVT
server's environment variables must be set so that FML field tables and viewfiles needed for message filtering and formatting are available. They could be set in the machine's or server's environment file.
*SERVERS
TMUSREVT SRVGRP=ADMIN1 SRVID=100 RESTART=Y MAXGEN=5 GRACE=3600
CLOPT="-A --"
TMUSREVT SRVGRP=ADMIN2 SRVID=100 RESTART=Y MAXGEN=5 GRACE=3600
CLOPT="-A -- -S -p 120"
tppost(3c), tpsubscribe(3c), EVENTS(5)
, EVENT_MIB(5)
, TMSYSEVT(5)
tperrno
—BEA Tuxedo system error codes
#include <atmi.h>
The numerical value represented by the symbolic name of an error condition is assigned to tperrno
for errors that occur when executing a BEA Tuxedo system library routine.
The name tperrno
expands to a modifiable lvalue
that has type int
, the value of which is set to a positive error number by several BEA Tuxedo system library routines. tperrno
need not be the identifier of an object; it might expand to a modifiable lvalue
resulting from a function call. It is unspecified whether tperrno
is a macro or an identifier declared with external linkage. If a tperrno
macro definition is suppressed to access an actual object, or if a program defines an identifier with the name tperrno
, the behavior is undefined.
The reference pages for BEA Tuxedo system library routines list possible error conditions for each routine and the meaning of the error in that context. The order in which possible errors are listed is not significant and does not imply precedence. The value of tperrno
should be checked only after an error has been indicated; that is, when the return value of the component indicates an error and the component definition specifies that tperrno
is set on error. An application that checks the value of tperrno
must include the <atmi.h>
header file.
The following list describes the general meaning of each error:
A transaction could not commit because either the work performed by the initiator or by one or more of its participants could not commit.
A call descriptor is invalid or is not the descriptor with which a conversational service was invoked.
The enqueuing of a message on the specified queue failed. The reason for failure can be determined by the diagnostic returned via ctl.
Due to some failure, the work done on behalf of the transaction could have been heuristically completed.
Due to a heuristic decision, the work done on behalf of the transaction was partially committed and partially aborted.
The type and subtype of the input buffer is not one of the types and subtypes that the service accepts.
The caller's request was not sent because the maximum number of outstanding requests or connections has been reached.
The administrative request failed. outbuf
is updated and returned to the caller with FML32 fields indicating the cause of the error, as described in MIB(5)
and TM_MIB(5)
.
A client cannot join an application because it does not have permission to do so or because it has not supplied the correct application password.
When the TPACK
is set and the target is a client from a prior release of the BEA Tuxedo system that does not support the acknowledgment protocol.
A service routine encountered an error either in tpreturn()
or tpforward()
(for example, bad arguments were passed).
The service routine sending the caller's reply called tpreturn()
with TPFAIL
. This is an application-level failure.
This error code indicates that either a timeout has occurred or a transactional ATMI function has been attempted, in spite of the fact that the current transaction is already marked rollback only.
If the caller is in transaction mode, then either the transaction is already rollback only or a transaction timeout has occurred. The transaction is marked abort-only. If the caller is not in transaction mode, a blocking timeout has occurred. (A blocking timeout cannot occur if TPNOBLOCK
and/or TPNOTIME
is specified.) In either case, no changes are made to *odata
, its contents, or *olen
.
If a transaction timeout has occurred, then, with one exception, any attempts to send new requests or receive outstanding replies will fail with TPETIME
until the transaction has been aborted. The exception is a request that does not block, expects no reply, and is not sent on behalf of the caller's transaction (that is, tpacall()
with TPNOTRAN
, TPNOBLOCK
, and TPNOREPLY
set).
When a service fails inside a transaction, the transaction is put into the TX_ROLLBACK_ONLY
state. This state is treated, for most purposes, as though it were equivalent to a timeout. All further ATMI calls for this transaction (with the exception of those issued in the circumstances described in the previous paragraph) will fail with TPETIME
.
Some routines do not have an error return value. Because no routine sets tperrno
to zero, an application can set tperrno
to zero, call a routine and then check tperrno
again to see if an error has occurred.
See the ERRORS
section of the individual BEA Tuxedo library routines for a more detailed description of the meaning of the error codes returned by each routine.
tpurcode
—BEA Tuxedo system global variable for an application-specified return code
#include <atmi.h>
tpurcode
is a global variable defined in atmi.h
. Its value is the same long integer used as the value of the rcode
argument of tpreturn()
. tpurcode
may be used by the application to return additional information to the process that calls an application service. For details, see tpreturn()
.
Assigning meanings to values in tpurcode
is the responsibility of the application.
Following are examples showing the use of tpurcode
:
If you return the value myval
through rcode
in an application service:
.
.
.
tpreturn(TPSUCCESS, myval, rqst->data, 0L, 0);
.
.
.
Then the code in the client module might be as follows:
.
.
.
ret = tpcall("TOUPPER", (char *)sendbuf, 0, (char **)&rcvbuf, \ &rcvlen, (long)0);
.
.
.
(void) fprintf(stdout, "Returned string is: %s\n", rcvbuf);
(void) fprintf(stdout, "Returned tpurcode is: %d\n", tpurcode);
If we call the sample client, simpcl
, with the value of "My String
," the output will look like this:
%simpcl "My String"
Returned string is: MY STRING
Returned tpurcode is: myval
The significance of myval
must be defined by the application.
tuxenv
—List of environment variables in the BEA Tuxedo system
In order to compile application clients and servers, and run the BEA Tuxedo system, it is important that the proper environment variables be set and exported. This reference page provides a list of the most frequently used variables.
The environment variables are grouped in the following sections:
TLOG
VariablesUsed to set the locale for language specification. See nl_types(5)
.
Specifies the pathname for the message catalog. If not specified, a default path is used. See nlpaths
(5).
Specifies the paging command used for paging output in qmadmin(1), tmadmin(1). This overrides the system default (pg(1) on UNIX operating systems).
The pathname of a directory in which temporary files may be written. Temporary files may also be written to a location specific to an operating system, as specified with the tmpnam()
function, which is called by the BEA Tuxedo MIB and other BEA Tuxedo code. When a call is made to tmpnam()
, the BEA Tuxedo system ignores the TMPDIR
variable.
Note that for BEA Tuxedo release 6.5 or earlier, the BEA Tuxedo code responsible for transferring message files from clients to service queues would write a message file to the temporary location specified with the tmpnam()
function if the service queue was too full to hold the message file; the code would then place the pathname of the temporary location on the service queue. For BEA Tuxedo release 7.1 or later, this code operates just like it did in previous releases except that the temporary location, if needed, is the pathname of the directory specified by TMPDIR
assuming that the variable is set; if TMPDIR
is not set, the temporary location becomes the one specified by the underlying operating system.
More information on these variables is available in the UNIX system reference page environ
(5).
In general, the following environment variables should be set and exported:
May be used to specify a password for system clients that prompt for an application password (when security is on). Setting the password in a variable allows the password to be provided from a script, rather than demanding manual entry.
This variable is used by tmloadcf(1). It customarily contains setting for other BEA Tuxedo system environment variable, which are set automatically by the system.
The pathname for the transaction log. This should be the same as the TLOGDEVICE
specified in the configuration file for the application.
Specifies the code-set encoding name that the application server or client running BEA Tuxedo 8.1 or later includes in an allocated MBSTRING typed buffer. When an application server or client process allocates and sends an MBSTRING buffer, the code-set encoding name defined in TPMBENC
is automatically added as an attribute to the buffer and sent with the buffer data to the destination process.
When the application server or client process receives an MBSTRING buffer, and assuming another environment variable named TPMBACONV
is set, the code-set encoding name defined in TPMBENC
is automatically compared to the code-set encoding name in the received buffer; if the names are not the same, the MBSTRING buffer data is automatically converted to the encoding defined in TPMBENC
before being delivered to the server or client process.
TPMBENC
has no default value. For an application server or client using MBSTRING typed buffers, TPMBENC
must be defined.
Specifies whether the application server or client running BEA Tuxedo 8.1 or later automatically converts the data in a received MBSTRING buffer to the encoding defined in TPMBENC
. By default, the automatic conversion is turned off, meaning that the data in the received MBSTRING buffer is delivered to the destination server or client process as is—no encoding conversion. Setting TPMBACONV
to any non-NULL value, say Y
(yes), turns on the automatic conversion.
Specifies whether the application server or workstation machine running BEA Tuxedo 8.1 or later software caches Document Type Definition (DTD), XML schema, and entity files; specifically, whether the Apache Xerces-C++ parser running on the application server or workstation machine caches the DTD and XML schema files when validation is required, or caches external entity files called out in the DTD. By default, the caching is turned on (Y
). Setting URLENTITYCACHING
to N
(no) turns off the caching.
Applies only if URLENTITYCACHING=Y
(yes) or is not set; for details, see the description of URLENTITYCACHING
in this list.
Specifies the directory in which the application server or workstation machine running BEA Tuxedo 8.1 or later software caches DTD, schema, and entity files; specifically, where the Apache Xerces-C++ parser running on the application server or workstation machine caches the DTD, XML schema, and entity files. The URLENTITYCACHEDIR
variable specifies the absolute pathname for the cached files. If URLENTITYCACHEDIR
is not specified, the default directory becomes URLEntityCachedir
, which will be created in the current working directory of the application server or Workstation client process provided that the appropriate write permissions are set.
More information about these variables can be found in Programming a BEA Tuxedo ATMI Application Using C, Setting Up a BEA Tuxedo Application, and Administering a BEA Tuxedo Application at Run Time.
The following environment variables are used by FML and VIEWS:
More information about these variables can be found in Setting Up a BEA Tuxedo Application, Administering a BEA Tuxedo Application at Run Time, Programming a BEA Tuxedo ATMI Application Using C, and Programming a BEA Tuxedo ATMI Application Using FML.
The following variables are used by the BEA Tuxedo system filesystem and the transaction log.
The following variables are used on Workstation client machines:
Determines whether the workstation machine running BEA Tuxedo 7.1 or later software is allowed to interoperate with pre-release 7.1 BEA Tuxedo applications. Setting the variable to Y
(WSINTOPPRE71=Y
) allows interoperability.
The network device to be used for network access. For Workstation clients in BEA Tuxedo release 6.4 and higher, this variable is no longer required.
The network address used by the Workstation client when connecting to other machines. This variable, along with the WSFRANGE
variable, determine the range of TCP/IP ports to which a process attempts to bind before making an outbound connection.
The range of TCP/IP ports to which a native process attempts to bind before making an outbound connection. The WSFADDR
variable specifies the base address of the range.
More information on these variables can be found in Using the BEA Tuxedo ATMI Workstation Component.
The following environment variable is used by BEA Tuxedo /Q:
Used to enable /Q to continue to work even though TMQFORWARD
is terminated abnormally without holding locks. When this variable is set to yes/YES
, if TMQFORWARD
is shutdown abnormally, (for example, hung due to application server hanging), when shutdown request is sent to TMQFORWARD
, and TMQFORWARD
does not hold any /Q locks, the /Q can work normally and TMQFORWARD
can be restarted later. Otherwise, if TMQFORWARD
terminated abnormally, /Q will be marked as insane and must be restarted.
There is more information on this in Using the ATMI /Q Component.
The following environment variables are used with COBOL:
Note: On a Windows system, the ALTCC
and ALTCFLAGS
environment variables are not applicable and setting them will produce unexpected results. You must compile your application first using a COBOL compiler and then pass the resulting object file to the buildclient(1) or buildserver(1) command.
There is more information on these variables in the Programming a BEA Tuxedo ATMI Application Using COBOL.
The following additional environment variables may be of use:
Specifies the number of message catalog handles to keep open (BEA Tuxedo system messages only). The default is 3.
In MP mode, can be used to specify the physical machine ID. In addition, in a high availability (HA) environment, PMID
can be used to replace the machine name specified in the UBBCONFIG
file with an alternate machine name. This allows for moving a master machine from master to backup in an HA cluster.
Used to specify whether compression should be used on messages and to set thresholds for both local and remote messages. The syntax of the variable is:
A threshold is a number in the range 0 to MAXLONG
. It sets the minimum byte size of a message on which data compression will be performed.
This variable sets the compression level for any process that picks it up. Valid values are the integers 1 through 9; 1 results in somewhat less compression that the higher levels, but takes place faster. An informational ULOG
message is written when a process reads TMCMPPRFM
.
Used to establish load balancing over a network. The value is an arbitrary number of units to be added to the load factor of remote services. Use of this variable tends to force the use of a local service.
To turn off multithreaded processing, set this variable to yes
. For applications that do not use threads, turning them off should significantly improve performance by reducing the amount of calls to mutexing functions.
Used to specify the amount of service and interface caching on a per-process basis. Valid values are the integers 0 through 32767. The value set for this variable will override any value in the UBBCONFIG
file.
Through this environment variable, Tuxedo 9.x allows you to adjust the maximum size of a shared memory segment accessible by Tuxedo to something other than the Tuxedo imposed default for the operating system. The Tuxedo system imposes a default shared memory segment maximum on its use of shared memory. This Tuxedo imposed limit can be lower than the maximum memory segment size tuned in the users kernel.
This environment variable should be set to the number of Mega-bytes that a shared memory segment should be set to. For example, if you want to set the segment size to 500MB, you would issue the following command in the tuxedo environment:
The logic is implemented such that the maximum shared memory segment used by Tuxedo will be set to 500 * (1024 * 1024) for a total of 524,288,000 bytes. If the environment variable is not set, then the Tuxedo default size for the given operating system will be used.
This environment variable is used in MBSTRING codeset conversion to keep compatible with ICU standard. The default is GNU standard. TM_ICU_COMPATIBILITY
can be set as follows:
This environment variable is for old-style security check. This should be set in the environment of GWTDOMAIN
. This variable will not affect any other Tuxedo processes even if set for them. It is used to make interdomain transactional requests between Tuxedo 6.5 and other Tuxedo releases work when the Tuxedo domain running on Tuxedo 6.5 cannot upgrade to patch level 446.
Note: When the Tuxedo 6.5 domain is upgraded to patch level 446 or later, this environment variable should be removed.
If TM_GWT_OLDSECCHECK=Y
, the old-style security check is used by GWTDOMAIN
. This is necessary to interoperate with Tuxedo 6.5 patches before patchlev 446. However, this implies weaker security. If TM_GWT_OLDSECCHECK=Y
, the GWTDOMAIN
process writes an informational ULOG message indicating that fact, when it receives the first incoming data/connection from the network.
If TM_GWT_OLDSECCHECK=N
or if TM_GWT_OLDSECCHECK
is not set, the latest security check is used. This implies that all the interoperating Tuxedo 6.5 domains should be at least at patchlev 446.
This environment variable is used to add detailed information to ULOG when TPSYSTEM
error occurs. TM_LOG_ESYS
is limited to ATMI calls and can be set as follows:
export TM_LOG_ESYS=all
(same as
export TM_LOG_ESYS=native
export TM_LOG_ESYS=native:ws
export TM_LOG_ESYS=native:ws:domain"all"
)
Used to help reduce the amount of error messages sent to the user log and event broker.
Note: User should set
an arbitrary string to turn TUX_BLOCKLICIW
on and unset
to turn off.
CMDTUX_CAT:4749 WARN: Reached 100% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4753 INFO: Reached 90% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4729 WARN: Reached 100% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4731 INFO: Reached 90% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4750 WARN: .SysLicenseWarn: Reached 100%% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4754 INFO: .SysLicenseInfo: Reached 90%% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4730 WARN: .SysLicenseWarn: Reached 100%% of TUXEDO System Binary Licensed User Count
CMDTUX_CAT:4732 INFO: .SysLicenseInfo: Reached 90%% of TUXEDO System Binary Licensed User Count
buildclient(1), buildserver(1), viewc, viewc32(1)
cc(1)
, environ
(5) in a UNIX system reference manual
tuxtypes
—Buffer type switch; descriptions of buffer types provided by the BEA Tuxedo system
/*
* The following definitions are specified in
* $TUXDIR/lib/tmtypesw.c
*/
#include <stdio.h>
#include <tmtypes.h>
/*
* Initialization of the buffer type switch.
*/
struct tmtype_sw_t tm_typesw[] = {
{
"CARRAY", /* type */
"*", /* subtype */
0 /* dfltsize */
NULL, /* initbuf */
NULL, /* reinitbuf */
NULL, /* uninitbuf */
NULL, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
NULL, /* encdec */
NULL, /* route */
NULL, /* filter */
NULL, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"STRING", /* type */
"*", /* subtype */
512, /* dfltsize */
NULL, /* initbuf */
NULL, /* reinitbuf */
NULL, /* uninitbuf */
_strpresend, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
_strencdec, /* encdec */
NULL, /* route */
_sfilter, /* filter */
_sformat, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"FML", /* type */
"*", /* subtype */
1024, /* dfltsize */
_finit, /* initbuf */
_freinit, /* reinitbuf */
_funinit, /* uninitbuf */
_fpresend, /* presend */
_fpostsend, /* postsend */
_fpostrecv, /* postrecv */
_fencdec, /* encdec */
_froute, /* route */
_ffilter, /* filter */
_fformat, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"VIEW", /* type */
"*", /* subtype */
1024, /* dfltsize */
_vinit, /* initbuf */
_vreinit, /* reinitbuf */
NULL, /* uninitbuf */
_vpresend, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
_vencdec, /* encdec */
_vroute, /* route */
_vfilter, /* filter */
_vformat, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
/* XATMI - identical to CARRAY */
"X_OCTET", /* type */
"*", /* subtype */
0 /* dfltsize */
},
{ /* XATMI - identical to VIEW */
{'X','_','C','_','T','Y','P','E'}, /* type */
"*", /* subtype */
1024, /* dfltsize */
_vinit, /* initbuf */
_vreinit, /* reinitbuf */
NULL, /* uninitbuf */
_vpresend, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
_vencdec, /* encdec */
_vroute, /* route */
_vfilter, /* filter */
_vformat, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
/* XATMI - identical to VIEW */
{'X','_','C','O','M','M','O','N'}, /* type */
"*", /* subtype */
1024, /* dfltsize */
_vinit, /* initbuf */
_vreinit, /* reinitbuf */
NULL, /* uninitbuf */
_vpresend, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
_vencdec, /* encdec */
_vroute, /* route */
_vfilter, /* filter */
_vformat, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"FML32", /* type */
"*", /* subtype */
1024, /* dfltsize */
_finit32, /* initbuf */
_freinit32, /* reinitbuf */
_funinit32, /* uninitbuf */
_fpresend32, /* presend */
_fpostsend32, /* postsend */
_fpostrecv32, /* postrecv */
_fencdec32, /* encdec */
_froute32, /* route */
_ffilter32, /* filter */
_fformat32, /* format */
_fpresend232 /* presend2 */
_fmbconv32 /* multibyte code-set encoding conversion */
},
{
"VIEW32", /* type */
"*", /* subtype */
1024, /* dfltsize */
_vinit32, /* initbuf */
_vreinit32, /* reinitbuf */
NULL, /* uninitbuf */
_vpresend32, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
_vencdec32, /* encdec */
_vroute32, /* route */
_vfilter32, /* filter */
_vformat32, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"XML", /* type */
"*", /* subtype */
0, /* dfltsize */
NULL, /* initbuf */
NULL, /* reinitbuf */
NULL, /* uninitbuf */
NULL, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
NULL, /* encdec */
_xroute, /* route */
NULL, /* filter */
NULL, /* format */
NULL, /* presend2 */
NULL /* multibyte code-set encoding conversion */
},
{
"MBSTRING", /* type */
"*", /* subtype */
0, /* dfltsize */
_mbsinit, /* initbuf */
NULL, /* reinitbuf */
NULL, /* uninitbuf */
_mbspresend, /* presend */
NULL, /* postsend */
NULL, /* postrecv */
NULL, /* encdec */
NULL, /* route */
NULL, /* filter */
NULL, /* format */
NULL, /* presend2 */
_mbsconv /* multibyte code-set encoding conversion */
},
{
""
}
};
struct tmtype_sw_t _TM_FAR *
_TMDLLENTRY
_tmtypeswaddr(void)
{
return(tm_typesw);
}
The following table lists the 11 buffer types provided by the BEA Tuxedo system.
Note that all VIEW, X_C_TYPE, and X_COMMON buffers are handled by the same set of routines; the name of a particular view is its subtype name.
An application programmer who wants to supply a custom buffer type can do so by adding an instance to the tm_typesw
array shown above. Whenever a new buffer type is added or one is deleted, care should be taken to leave a NULL
entry at the end of the array as shown above. Note that a buffer type with a NULL
name is not permitted.
A copy of the default array is delivered in $TUXDIR/lib/tmtypesw.c
, and may be used as a starting point. The recommended procedure for installing a new buffer type switch is to compile tmtypesw.c
and store it as the only element in a library named libbuft
.
On systems with shared object capability, build and install a new instance of libbuft.so.
under $TUXDIR/lib
. All processes, including BEA Tuxedo system processes like WSH
, will then automatically have access to the new type switch without recompilation. On a Windows workstation, the shared object for the buffer type switch is named WBUFT.DLL
. It should be stored in $TUXDIR\bin
.
On systems without shared object capability, build and install a new instance of libbuft.a
under $TUXDIR/lib
. All processes needing to know about the new types must then be rebuilt, using buildclient(1) or buildserver(1). System processes like WSH
may need to be rebuilt using special commands such as buildwsh(1).
See buffer(3c) for a description of the elements and routines in the buffer type switch. Also found there is a description of built in routines provided by the BEA Tuxedo system (for example, _finit()
) that applications can use when changing the system-provided buffer types.
The three routing functions provided by the system, _froute()
, _vroute()
, and _xroute()
, are used for data-dependent routing of FML buffers, VIEW buffers, and XML buffers, respectively. See UBBCONFIG(5)
for instructions on defining the routing criteria to be used by these three functions.
$TUXDIR/tuxedo/include/tmtypes.h—the type switch definition
$TUXDIR/lib/tmtypesw.c—the default type switch instantiation
$TUXDIR/lib/libbuft.so.—type switch shared object
$TUXDIR/lib/libbuft.a—type switch archive library
buffer(3c), typesw(5)
, UBBCONFIG(5)
typesw
—Buffer type switch structure; parameters and routines needed for each buffer type
/*
* The following definitions are in $TUXDIR/include/tmtypes.h
*/
#define TMTYPELEN ED_TYPELEN
#define TMSTYPELEN ED_STYPELEN
struct tmtype_sw_t {
char type[TMTYPELEN]; /* type of buffer */
char subtype[TMSTYPELEN]; /* subtype of buffer */
long dfltsize; /* default size of buffer */
/* buffer initialization function pointer */
int (_TMDLLENTRY *initbuf) _((char _TM_FAR *, long));
/* buffer reinitialization function pointer */
int (_TMDLLENTRY *reinitbuf) _((char _TM_FAR *, long));
/* buffer un-initialization function pointer */
int (_TMDLLENTRY *uninitbuf) _((char _TM_FAR *, long));
/* pre-send buffer manipulation func pointer */
long (_TMDLLENTRY *presend) _((char _TM_FAR *, long, long));
/* post-send buffer manipulation func pointer */
void (_TMDLLENTRY *postsend) _((char _TM_FAR *, long, long));
/* post-receive buffer manipulation func pointer*/
long (_TMDLLENTRY *postrecv) _((char _TM_FAR *, long, long));
/* XDR encode/decode function pointer */
long (_TMDLLENTRY *encdec) _((int, char _TM_FAR *, long, char _TM_FAR *, long));
/* routing function pointer */
int (_TMDLLENTRY *route) _((char _TM_FAR *, char _TM_FAR *, char _TM_FAR *,
long, char _TM_FAR *));
/* buffer filtering function pointer */
int (_TMDLLENTRY *filter) _((char _TM_FAR *, long, char _TM_FAR *, long));
/* buffer formatting function pointer */
int (_TMDLLENTRY *format) _((char _TM_FAR *, long, char _TM_FAR *,
char _TM_FAR *, long));
/* process buffer before sending, possibly generating copy */
long (_TMDLLENTRY *presend2) _((char _TM_FAR *, long,
long, char _TM_FAR *, long, long _TM_FAR *));
/* Multibyte code-set encoding conversion function pointer*/
long (_TMDLLENTRY *mbconv) _((char _TM_FAR *, long,
char _TM_FAR *, char _TM_FAR *, long, long _TM_FAR *));
/* this space reserved for future expansion */
void (_TMDLLENTRY *reserved[8]) _((void));
};
/*
* application types switch pointer
* always use this pointer when accessing the table
*/
extern struct tmtype_sw_t *tm_typeswp;
Each buffer type and subtype must have an entry in the tm_typesw
array such that when a buffer is manipulated the appropriate routines are called. For the buffer types provided by the BEA Tuxedo system, see tuxtypes(5)
.
An application programmer who wants to supply a customized buffer type can do so by adding an instance to the tm_typesw
array in $TUXDIR/lib/tmtypesw.c.
(tuxtypes(5)
shows how this can be done.) The semantics of the routines that must be supplied when adding a new type are specified in buffer(3c).
$TUXDIR/tuxedo/include/tmtypes.h—the type switch definition
$TUXDIR/lib/tmtypesw.c—the type switch instantiation
buffer(3c), tuxtypes(5)
UBBCONFIG
—Text version of a BEA Tuxedo configuration file
When a BEA Tuxedo application is booted, the tmboot
command refers to a binary configuration file called TUXCONFIG
to get the information necessary for starting application servers and initializing the bulletin boards in an orderly sequence. This binary file cannot be created directly; it must be created from a text file called UBBCONFIG
. To configure an application, an administrator creates a UBBCONFIG
file (with a text editor) and loads the file into a binary version (TUXCONFIG
) by running the tmloadcf(1) command. During the life of the application, the TUXCONFIG
file is used by various BEA Tuxedo administrative tools. tmadmin(1) uses the configuration file (or a copy of it) in its monitoring activity. tmshutdown(1) references the configuration file for information needed to shut the application down.
A BEA Tuxedo UBBCONFIG
file may be given any name as long as the content of the file conforms to the format described on this reference page. In addition, the TUXCONFIG
file may be given any name; the actual name is the device or system filename specified in the TUXCONFIG
environment variable.
For additional information pertaining to the entire UBBCONFIG
file, see UBBCONFIG(5) Additional Information.
A server is a process that accepts requests and sends replies for clients and other servers. A client originates requests and gets replies.
A resource manager is an interface and associated software providing access to a collection of information and/or processes. An example of a resource manager is a database management system; a resource manager instance is a particular instantiation of a database controlled by a DBMS. A distributed transaction is a transaction that spans multiple resource manager instances, is started with tpbegin()
, and ended with tpcommit()
or tpabort()
.
A server group is a resource manager instance and the collection of servers and/or services providing access to that resource manager instance on a particular machine. The XA interface associated with the group is used for transaction management. If a server does not access a resource manager instance or does not access it as part of a distributed transaction, it must be in a server group with a NULL XA interface. Similarly, clients run in a special client group that does not have to be specified in the GROUPS
section. The client group is not associated with a resource manager.
A remote domain is defined to be an environment for which the bulletin board for this BEA Tuxedo system configuration is not available. Remote domains are not specified in the UBBCONFIG
file, but rather through host-specific environment variables that are specified in host-specific reference pages.
A UBBCONFIG
file is made up of nine possible specification sections. Lines beginning with an asterisk (*
) indicate the beginning of a specification section. Each such line contains the name of the section immediately following the *
. Allowable section names are:
The RESOURCES
and MACHINES
sections must be the first two sections and must be included in that order. The GROUPS
section must precede the SERVERS
, SERVICES
, and ROUTING
sections. The NETGROUPS
section must precede the NETWORK
section.
Parameters (except in the RESOURCES
section) are generally specified by: KEYWORD
=
value
; white space (space or tab character) is allowed on either side of the equal sign (=
). This format sets KEYWORD
to value
. Valid keywords are described within each section.
Lines beginning with the reserved word DEFAULT
contain parameter specifications that apply to any lines that follow them in the section in which they appear. Default specifications can be used in all sections other than the RESOURCES
section. They can appear more than once in the same section. The format for these lines is:
DEFAULT:
[optional
KEYWORD
=
value
pairs
]
The values set on this line remain in effect until reset by another DEFAULT
line, or until the end of the section is reached. These values can also be overridden on non-DEFAULT
lines by placing the optional parameter setting on the line. If on a non-DEFAULT
line, the parameter setting is valid for that line only; lines that follow revert to the default setting. If DEFAULT
appears on a line by itself, all previously set defaults are cleared and their values revert to the system defaults.
If a value is numeric
, standard C notation is used to denote the base, that is, 0x prefix for base 16 (hexadecimal), 0 prefix for base 8 (octal), and no prefix for base 10 (decimal). The range of acceptable values for a numeric parameter is given under the description of that parameter.
If a value is an identifier
(a string value already known to the BEA Tuxedo system such as APP_PW
for the SECURITY
parameter), standard C rules are typically used. A standard C identifier
starts with an alphabetic character or underscore and contains only alphanumeric characters or underscores. The maximum allowable length of an identifier is 30 (not including the terminating NULL).
Note: There is no need to enclose an identifier in double quotes.
A value that is neither an integer number nor an identifier must be enclosed in double quotes. This value is a user-defined string
. The maximum allowable length of a user-defined string is 78 characters (bytes), not including the terminating NULL. Exceptions to this rule are as follows:
CLOPT
, BUFTYPE
, OPENINFO
, and CLOSEINFO
parameters, which can be 256 characters in lengthTUXCONFIG
, TUXDIR
, APPDIR
, TLOGDEVICE
, ULOGPFX
, ENVFILE
, TMSNAME
, RCMD
, NADDR
, NLSADDR
, FADDR
, and AOUT
(in SERVERS
section) parameters, which can be 256 characters in length as of BEA Tuxedo release 8.1; string values for these parameters are limited to 78 characters in length for BEA Tuxedo 8.0 or earlier.SEC_PRINCIPAL_NAME
, SEC_PRINCIPAL_LOCATION
, and SEC_PRINCIPAL_PASSVAR
parameters, which can be 511 characters in length (not including the terminating NULL)RANGES
parameter, which can be 2048 characters in length (except in Domains, where it can be 4096 characters in length)In the RANGES
parameter of the ROUTING
section, certain special characters can be escaped inside a string using a backslash.
"\\" translates to a single backslash
"\"" translates to a double quote
"\n" translates to a newline
"\t" translates to a tab
"\f" translates to a formfeed
"\O+" translates to a character whose octal value is O+
where O+
is one, two, or three octal characters. "\0
" translates to an embedded NULL character. "\xH+
" or "\XH+
" translates to a character whose hexadecimal value is H+
where H+
is one or more hexadecimal characters. "\y
" (where `y' is any character other than one of the previously mentioned characters) translates to `y'; this produces a warning.
"#
" (pound sign) introduces a comment. A newline ends a comment.
An identifier or a numeric constant must always be followed by white space (space or tab character), a newline character, or a punctuation character (pound sign, equals sign, asterisk, colon, comma, backslash, or period).
Blank lines and comments are ignored.
Comments can be freely attached to the end of any line.
Lines are continued by placing at least one tab after the newline. Comments cannot be continued.