e-docs > Tuxedo > File Formats, Data Descriptions, MIBs, and System Processes Reference > Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference |
File Formats, Data Descriptions, MIBs, and System Processes Reference |
TM_MIB(5) Additional Information
Diagnostics
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.
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.
Interoperability
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.
Portability
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.
Examples
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.
Field Tables
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
Header Files
The following header files are included.
#include <atmi.h>
#include <fml32.h>
#include <tpadm.h>
Libraries
${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
Initial Configuration
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 */
}
Add Second Machine
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 */
Make Second Machine Backup Master
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 */
Add Two Server Groups
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 */
Add One Server Per Group
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 Routing Criteria
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 */
Add Service Definition
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 Master Site Admin
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 */
Switch to Active Application Administration
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 Rest of Application
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 */
}
Query Server Status
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 Application
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 */
Files
${TUXDIR}/include/tpadm.h, ${TUXDIR}/udataobj/tpadm
See Also
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
TMFFNAME(5)
Synopsis
Server that runs the FactoryFinder and supporting NameManager services.
Syntax
TMFFNAME SRVGRP="identifier" SRVID="number"
[CLOPT="[-A] [servopts options]
[-- [-F ] [-N | -N -M [-f filename]]]"]
Description
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.
Parameters
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.
Interoperability
The TMFFNAME servers run on BEA Tuxedo version 4.0 software and later.
Notes
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.
Example
*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"
See Also
factory_finder.ini(5), TMSYSEVT(5), UBBCONFIG(5), userlog(3c)
, TP Framework in BEA Tuxedo CORBA Programming Reference.
TMIFRSVR(5)
Name
The Interface Repository server
Synopsis
TMIFRSVR SRVGRP="identifier" SRVID="number" RESTART=Y GRACE=0 CLOPT="[servopts options] -- [-f repository_file_name]"
Description
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.
Parameter
Examples
*SERVERS
#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"
See Also
ir2idl(1), UBBCONFIG(5), servopts(5)
TMQFORWARD(5)
Name
TMQFORWARD—Message Forwarding server
Synopsis
TMQFORWARD SRVGRP="identifier" SRVID="number" REPLYQ=N CLOPT="
[-A] [servopts options] -- -q queuename[,queuename...]
[-t trantime ] [-i idletime] [-e] [-d] [-n] [-f delay] "
Description
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.
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:
Handling Application Buffer Types
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:
The -s option must not be specified to advertise services.
Portability
TMQFORWARD is supported as a BEA Tuxedo system-supplied server on all supported server platforms.
Interoperability
TMQFORWARD may be run in an interoperating application, but it must run on a BEA Tuxedo release 4.2 or later node.
Examples
*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"
See Also
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(5)
Name
TMQUEUE—Message Queue Manager
Synopsis
TMQUEUE
SRVGRP="identifier"
SRVID="number" CLOPT=" [-A][servopts options] -- [-t timeout]"
Description
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.
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.
Queue Name for Message Submission
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).
Handling Application Buffer Types
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:
Portability
TMQUEUE is supported as a BEA Tuxedo system-supplied server on all supported server platforms.
Interoperability
TMQUEUE may be run in an interoperating application, but it must run on a BEA Tuxedo release 4.2 or later node.
Examples
*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.
See Also
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(5)
Name
TMSYSEVT—System event reporting process
Synopsis
TMSYSEVT SRVGRP="identifier" SRVID="number"
[CLOPT="[-A] [servopts options]
[-- [-S] [-p poll-seconds] [-f control-file]]"]
Description
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.
Interoperability
TMSYSEVT must run on a BEA Tuxedo release 6.0 or later machine.
Notices
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.
Example
*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"
See Also
tpsubscribe(3c)
, EVENTS(5), EVENT_MIB(5), TMUSREVT(5)
tmtrace(5)
Name
tmtrace—Run-time tracing facility
Description
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 Categories
The trace categories are:
xa
Trace Specification
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.
Filter Specification
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.
Receiver Specification
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.
Currently, the only legal value for receiver is:
Trigger Specification
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.
The available actions are
Trace Records
A trace record is a string with the format:
cc:data
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
Notices
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.
Examples
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 ENVFILEs 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 ENVFILEs 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"
See Also
tmadmin(1)
, userlog(3c)
TMUSREVT(5)
Name
TMUSREVT—User event reporting process
Synopsis
TMUSREVT SRVGRP="identifier" SRVID="number"
[CLOPT="[-A] [servopts options]
[-- [-S] [-p poll-seconds] [-f control-file]]"]
Description
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.
Interoperability
TMUSREVT must run on a BEA Tuxedo release 6.0 or later machine.
Notices
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.
Example
*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"
See Also
tppost(3c)
, tpsubscribe(3c), EVENTS(5), EVENT_MIB(5), TMSYSEVT(5)
tperrno(5)
Name
tperrno—BEA Tuxedo system error codes
Synopsis
#include <atmi.h>
Description
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:
Usage
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 Also
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(5)
Name
tpurcode—BEA Tuxedo system global variable for an application-specified return code
Synopsis
#include <atmi.h>
Description
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.
Examples
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.
See Also
tpreturn(3c)
tuxenv(5)
Name
tuxenv—List of environment variables in the BEA Tuxedo system
Description
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:
Operating System Variables
More information on these variables is available in the UNIX system reference page environ(5).
Key BEA Tuxedo System Variables
In general, the following environment variables should be set and exported:
Note: TPMBENC is used in a similar way for FLD_MBSTRING fields in an FML32 typed buffer.
Note: TPMBACONV is used in a similar way for FLD_MBSTRING fields in an FML32 typed buffer.
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.
Variables for Field Table Files and Viewfiles
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.
Filesystem and TLOG Variables
The following variables are used by the BEA Tuxedo system filesystem and the transaction log.
Workstation Variables
The following variables are used on Workstation client machines:
More information on these variables can be found in Using the BEA Tuxedo ATMI Workstation Component.
BEA Tuxedo /Q Variables
The following environment variable is used by BEA Tuxedo /Q:
There is more information on this in Using the ATMI /Q Component.
COBOL Variables
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.COBDIR
There is more information on these variables in the Programming a BEA Tuxedo ATMI Application Using COBOL.
Additional Miscellaneous Variables
The following additional environment variables may be of use:
See Also
buildclient(1)
, buildserver(1), viewc, viewc32(1)cc(1), environ(5) in a UNIX system reference manual
tuxtypes(5)
Name
tuxtypes—Buffer type switch; descriptions of buffer types provided by the BEA Tuxedo system
Synopsis
Default Buffer Type Switch
/*
* 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 */
NULL, /* 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);
}
Description
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)
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.
Files
$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
See Also
buffer(3c)
, typesw(5), UBBCONFIG(5)
typesw(5)
Name
typesw—Buffer type switch structure; parameters and routines needed for each buffer type
Synopsis
Buffer Type Structure
/*
* 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;
Description
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)
.Files
$TUXDIR/tuxedo/include/tmtypes.h—the type switch definition
$TUXDIR/lib/tmtypesw.c—the type switch instantiation
See Also
buffer(3c)
, tuxtypes(5)
UBBCONFIG(5)
Name
UBBCONFIG—Text version of a BEA Tuxedo configuration file
Description
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.
Definitions
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.
Configuration File Format
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:
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.