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.

[other]

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]

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.

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

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 [-ffilename]]]"]

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

-A

Advertise all services built into the server

-F

FactoryFinder service

-N

Slave NameManager service; this is the default.

-M

Master NameManager service

-f filename

Location of FactoryFinder import/export file

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.

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.

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"

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

[-f repository_file_name]

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.

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"

TMMETADATA(5)

Name

TMMETADATA - Tuxedo service metadata repository server

Synopsis

TMMETADATA SRVGRP="identifier" SRVID="number"

CLOPT="[-A] [servopts options] -- -f repository_file [-r]

Description

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:

-f

This option is mandatory and specifies the location of the metadata repository_file.

-r

If this option is specified, TMMETADATA only allows retrieve information requests from the metadata repository and disallows any metadata repository update requests. The TMMETADATA default permissions setting is read/write.

Limitation

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.

Interoperability

TMMETADATA must run on a Tuxedo 9.0 release or later.

Tuxedo Jolt Repository

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.

Example(s)

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"

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] [-b timeout] [-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.

-q queuename[,queuename...]

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.

-t trantime

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.

-i idletime

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.

-b timeout

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.

-e

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.

-d

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.

-n

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.

-f delay

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:

The SRVGRP must have TMSNAME set to TMS_QM.
OPENINFO must be set to indicate the associated device and queue name.
The SERVER entry must not be part of an MSSQ set.
REPLYQ must be set to N.
The -q option must be specified in the command-line options.
The server must not advertise any services (that is, the -s option must not be specified).

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:

-v

Specifies that buildserver should work in verbose mode. In particular, it writes the cc command to its standard output.

-o name

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.

-r TUXEDO/QM

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.

-f $TUXDIR/lib/TMQFORWARD.o

Specifies the object file that contains the TMQFORWARD service and should be specified as the first argument to the -f option.

-f firstfiles

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.

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"

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.

-t timeout

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.

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:

-v

Specifies that buildserver should work in verbose mode. In particular, it writes the cc command to its standard output.

-o name

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.

-s qspacename,qspacename :TMQUEUE

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.

-r TUXEDO/QM

-f $TUXDIR/lib/TMQUEUE.o

Specifies the object file that contains the TMQUEUE service and should be specified as the first argument to the -f option.

-f firstfiles

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.

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.

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.

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.

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"

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:

atmi

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).

iatmi

Trace points for Implicit 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).

xa

Trace points for every call to the XA interface (the interface between the Transaction Manager and a Resource Manager, for example, a database).

trace

Trace points related to the tracing feature itself, including message dyeing

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.

Legal receiver values are:

ulog

Outputs trace record information to the user log.

utrace

Outputs trace record information as defined by the user. The utrace receiver calls user-defined tputrace(3c) for atmi trace category records only. Users can customize trace record information and output location.

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

abort

Terminate the process by calling abort().

ulog(message)

Write the message to the user log.

system(command)

Execute the command using system(3) (this is not supported for Windows clients); occurrences of %A are expanded to the value of trace record.

trace(trace-spec)

Reset the trace specification to the supplied trace-spec.

dye

Turn on message dyeing.

undye

Turn off message dyeing.

sleep(seconds)

Sleep the specified number of seconds (this is not supported for Windows clients).

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"

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"

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:

TPEABORT

A transaction could not commit because either the work performed by the initiator or by one or more of its participants could not commit.

TPEBADDESC

A call descriptor is invalid or is not the descriptor with which a conversational service was invoked.

TPEBLOCK

A blocking condition exists and TPNOBLOCK was specified.

TPEDIAGNOSTIC

The enqueuing of a message on the specified queue failed. The reason for failure can be determined by the diagnostic returned via ctl.

TPEEVENT

An event occurred; the event type is returned in revent.

TPEGOTSIG

A signal was received and TPSIGRSTRT was not specified.

TPEHAZARD

Due to some failure, the work done on behalf of the transaction could have been heuristically completed.

TPEHEURISTIC

Due to a heuristic decision, the work done on behalf of the transaction was partially committed and partially aborted.

TPEINVAL

An invalid argument was detected.

TPEITYPE

The type and subtype of the input buffer is not one of the types and subtypes that the service accepts.

TPELIMIT

The caller's request was not sent because the maximum number of outstanding requests or connections has been reached.

TPEMATCH

svcname is already advertised for the server but with a function other than func.

TPEMIB

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).

TPENOENT

Cannot send to svc because it does not exist or is not the correct type of service.

TPEOS

An operating system error has occurred.

TPEOTYPE

The type and subtype of the reply are not known to the caller.

TPEPERM

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.

TPEPROTO

A library routine was called in an improper context.

TPERELEASE

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.

TPERMERR

A resource manager failed to open or close correctly.

TPESVCERR

A service routine encountered an error either in tpreturn() or tpforward() (for example, bad arguments were passed).

TPESVCFAIL

The service routine sending the caller's reply called tpreturn() with TPFAIL. This is an application-level failure.

TPESYSTEM

A BEA Tuxedo system error has occurred.

TPETIME

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.

TPETRAN

The caller cannot be placed in transaction mode.

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.

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.

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
Key BEA Tuxedo system Variables
Variables for Field Table Files and Viewfiles
Filesystem and TLOG Variables
Workstation Variables
BEA Tuxedo /Q Variables
COBOL Variables
DEBUG Variables
Additional Miscellaneous Variables

Operating System Variables

CC

Standard C compiler for use by buildserver and other BEA Tuxedo commands.

CFLAGS

Contains flags to be used by the C compiler.

EDITOR

Specifies the editor to be invoked by the BEA Tuxedo system.

LANG

Used to set the locale for language specification. See nl_types(5).

LOGNAME

Specifies the username for use in error messages.

LD_LIBRARY_PATH

Must be set to the pathname for run-time shared libraries.

NLSPATH

Specifies the pathname for the message catalog. If not specified, a default path is used. See nlpaths(5).

PAGER

Specifies the paging command used for paging output in qmadmin(1), tmadmin(1). This overrides the system default (pg(1) on UNIX operating systems).

PATH

Contains pathnames to be searched for executables.

SHELL

The shell program to be invoked by the BEA Tuxedo system.

TERM

Specifies terminal type, if a terminal is used.

TMPDIR

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.

TZ

On systems where the ANSI C mktime functions does not exist, TZ must be set to use the BEA Tuxedo gp_mktime(3c) function.

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:

APPDIR; APP_PW; ENVFILE; TLOGDEVICE; TUXCONFIG; TUXDIR; ULOGPFX; TPMBENC; TPMBACONV; URLENTITYCACHING; URLENTITYCACHEDIR

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:

FIELDTBLS

Comma-separated list of field table files.

VIEWFILES

Comma-separated list of binary viewfiles.

FLDTBLDIR

Colon-separated list of directories to search for FIELDTBLS files.

VIEWDIR

Colon-separated list of directories to search for VIEWFILES files.

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.

FSCONFIG

The pathname for the Universal Device List.

FSMAXCOMMIT

Sets the maximum size of the commit buffer.

FSMAXUPDATE

Sets the size of the update list and the maximum number of updates.

FSMSGREP

Sets the message repetition interval.

FSOFFSET

Specifies an offset into the Universal Device List.

Workstation Variables

The following variables are used on Workstation client machines:

TPMBENC

See Key BEA Tuxedo System Variables.

TPMBACONV

See Key BEA Tuxedo System Variables.

URLENTITYCACHING

See Key BEA Tuxedo System Variables.

URLENTITYCACHEDIR

See Key BEA Tuxedo System Variables.

WSINTOPPRE71

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.

WSBUFFERS

The number of packets per application.

WSDEVICE

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.

WSENVFILE

Pathname of a file containing Workstation client environment variables.

WSFADDR

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.

WSFRANGE

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.

WSNADDR

The network address of the native site network listener.

WSRPLYMAX

The maximum message size before a message is dumped to a file for transfer.

WSTYPE

The machine type of the workstation machine.

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:

QMCONFIG

Sets the device where queue space is available to BEA Tuxedo /Q.

ISSANE

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.

COBOL Variables

The following environment variables are used with COBOL:

ALTCC; ALTCFLAGS

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.

COBCPY

COBDIR

Specifies the directory where COBOL compiler software is located.

COBOPT; TM_ORB_CLTMAXRTY

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:

MHSCACHE; PMID; TAGENTLOG; TMCMPLIMIT; TMCMPPRFM; TMNETLOAD; TMNOTHREADS; TMSICACHEENTRIESMAX; TM_ENGINE_TMSHMSEGSZ; TM_GWT_OLDSECCHECK; TUX_BLOCKLICIW; UIMMEDSIGS

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 */
	_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);
}

Description

The following table lists the 11 buffer types provided by the BEA Tuxedo system.

CARRAY	Character array (possibly containing `NULL` characters) that is neither encoded nor decoded during transmission
STRING	`NULL`-terminated character array
FML	FML fielded buffer
VIEW	C structure or FML view
X_OCTET	Equivalent to CARRAY; provided for XATMI compatibility
X_C_TYPE	Equivalent to VIEW; provided for XATMI compatibility
X_ COMMON	Equivalent to VIEW; provided for XATMI compatibility
FML32	FML32 fielded buffer, using 32-bit identifiers and offsets
VIEW32	C structure or FML32 view, using 32-bit identifiers, counter variables, and size variables
XML	Buffer for XML documents
MBSTRING	Character array for multibyte characters

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.

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

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

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:

The CLOPT, BUFTYPE, OPENINFO, and CLOSEINFO parameters, which can be 256 characters in length
The TUXCONFIG, 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.
The SEC_PRINCIPAL_NAME, SEC_PRINCIPAL_LOCATION, and SEC_PRINCIPAL_PASSVAR parameters, which can be 511 characters in length (not including the terminating NULL)
The 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.

TM_MIB(5) Additional Information

Diagnostics

Interoperability

Portability

Examples

Field Tables

Header Files

Libraries

Initial Configuration

Add Second Machine

Make Second Machine Backup Master

Add Two Server Groups

Add One Server Per Group

Add Routing Criteria

Add Service Definition

Activate Master Site Admin

Switch to Active Application Administration

Activate Rest of Application

Query Server Status

Deactivate Application

Files

See Also

TMFFNAME(5)

Synopsis

Syntax

Description

Parameters

Interoperability

Notes

Example

See Also

TMIFRSVR(5)

Name

Synopsis

Description

Parameter

Examples

See Also

TMMETADATA(5)

Name

Synopsis

Description

Limitation

Interoperability

Example(s)

See Also

TMQFORWARD(5)

Name

Synopsis

Description

Handling Application Buffer Types

Portability

Interoperability

Examples

See Also

TMQUEUE(5)

Name

Synopsis

Description

Queue Name for Message Submission

Handling Application Buffer Types

Portability

Interoperability

Examples

See Also

TMSYSEVT(5)

Name

Synopsis

Description

Interoperability

Notices

Example

See Also

tmtrace(5)

Name

Description

Trace Categories

Trace Specification

Filter Specification

Receiver Specification