Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
WebLogic Enterprise Doc Home   |   Tuxedo ATMI Topics   |   Previous Topic   |   Next Topic   |   Contents   |   Index

The T_ULOG class represents run-time attributes of userlog(3c) files within an application.

Table 0-45 T_ULOG Class Definition Attribute Table

Attribute1	Type	Permissions	Values	Default
TA_LMID( k )	string	R--R--R--	LMID	(2)
TA_PMID( x )	string	R--R--R--	string[1...30]	(2)
TA_MMDDYY( k )	long	R--R--R--	mmddyy	Current date
TA_STATE	string	R--R--R--	GET:"{ACT}" SET:N/A	N/A N/A
TA_ULOGTIME( k )	long	R--R--R--	hhmmss	000000
TA_ENDTIME( k )	long	K--K--K--	hhmmss	235959
TA_ULOGLINE( k )	long	R--R--R--	1 <= num	1
TA_ULOGMSG( x )	string	R--R--R--	string[1...256]	N/A
TA_TPTRANID( k )	string	R--R--R--	string[1...78]	N/A
TA_XID( k )	string	R--R--R--	string[1...78]	N/A
TA_PID( k )	long	R--R--R--	1 <= num	N/A
TA_SEVERITY( x )	string	R--R--R--	string[1...30]	N/A
TA_ULOGCAT( x )	string	R--R--R--	string[1...30]	N/A
TA_ULOGMSGNUM( k )	long	R--R--R--	1 <= num	N/A
TA_ULOGPROCNM( x )	string	R--R--R--	string[1...30]	N/A
( k ) - GET key field ( x ) - Regular expression GET key field

¹All attributes in Class T_ULOG are local attributes.

²TA_LMID is a required field used by the system to determine which application log file should be accessed. It is not used to restrict returned records to only those generated from processes running on the indicated machine. In cases where multiple machines share a log file via a networked file system, multiple TA_LMID values may be returned even though a specific value has been provided as a key field. For the same reasons, TA_PMID is not considered in directing the request to a particular machine, but is used in determining which records should be returned. In this capacity, it may be useful to leverage TA_PMID as a regular expression key field.

TA_LMID: LMID

Retrieval machine logical machine identifier.

TA_PMID: string[1...30]

Physical machine identifier.

TA_MMDDYY: mmddyy

Date of userlog file found or to be accessed.

TA_STATE:

GET: {ACTive}

A GET operation will retrieve run-time information for the selected T_ULOG object(s). The following states indicate the meaning of a TA_STATE returned in response to a GET request. States not listed will not be returned.

ACTive

The object returned reflects an existing userlog file on the indicated logical machine.

SET:

SET operations are not permitted on this class.

TA_ULOGTIME: hhmmss

The time of the userlog message represented by this object. The value of this attribute is formed by multiplying the hour by 10,000, adding to that the minute multiplied by 100, and finally adding in the seconds. When used as a key field, this attribute represents the start of the time range to be accessed for messages.

TA_ENDTIME: hhmmss

The latest time to be considered in a GET operation when accessing this userlog file.

TA_ULOGLINE: 1 <= num

The line number of the userlog message returned/requested within the userlog file. When used as a key field for retrieval, this value indicates the starting line within the log file.

TA_ULOGMSG: string[1...256]

The entire text of the userlog message as it appears in the userlog file.

TA_TPTRANID: string[1...78]

Transaction identifier as returned from tpsuspend(3c). The data in this field should not be interpreted directly by the user except for equality comparison. Messages not associated with transactions will retrieve a 0-length string as the value for this attribute.

TA_XID: string[1...78]

Transaction identifier as returned from tx_info(3c). The data in this field should not be interpreted directly by the user except for equality comparison. Messages not associated with transactions will retrieve a 0-length string as the value for this attribute.

TA_PID: 1 <= num

Process identifier of the client or server that generated the userlog message.

TA_SEVERITY: string[1...30]

Severity of message, if any.

TA_ULOGCAT: string[1...30]

Catalog name from which the message was derived, if any.

TA_ULOGMSGNUM: 1 <= num

Catalog message number, if the message was derived from a catalog.

TA_ULOGPROCNM: string[1...30]

Process name of the client or server that generated the userlog message.

Retrievals may be done only if the associated T_MACHINE object is also ACTive.

Retrievals for this class must be directed, that is, the TA_LMID attribute must be specified. Retrievals of log records written by Workstation clients are available only if the log file used by the client is shared with one of the machines defined in the T_MACHINE class for the application. Otherwise, these log records are unavailable through this class.

Retrievals on this class which cannot be completely satisfied will always return a TA_MORE value of 1 indicating only that more information may be available for the originating request.

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(3c), tpgetrply(3c), and tpdequeue(3c)) 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, then failure may be returned in the form of an application level service failure. In these cases, tpcall(3c) and tpcall(3c) 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.

The header files and field tables defined in this reference page are available on BEA Tuxedo system Release 5.0 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 Release 5.0, are interoperating, then information on the older site is available for access and update as defined in the MIB reference page for that release and may be a subset of the information available in the later release.

The existing FML32 and ATMI functions necessary to support administrative interaction with BEA Tuxedo system MIBs, as well as the header file and field table defined in this reference page, are available on all supported native and workstation platforms.

This section contains a sequence of code fragments that configure, activate, query, and deactivate a two node application using both tpadmcall(3c) and tpcall(3c). Variable names are used in places where reasonable values for a local environment are required, for example, tuxconfig is a two element array of character pointers with each element identifying the full pathname of the TUXCONFIG file on that machine.

The field table tpadm must be available in the environment to have access to attribute field identifiers. This can be done at the shell level as follows:

$ FIELDTBLS=tpadm $ FLDTBLDIR=${TUXDIR}/udataobj$ export FIELDTBLS FLDTBLDIR

The following header files are included.

#include <atmi.h> #include <fml32.h>#include <tpadm.h>

The following code creates and populates an FML32 buffer that is then passed to tpadmcall(3c) for processing. This example also shows interpretation of tpadmcall(3) return codes. The request shown creates the initial configuration for the application.

/* Allocate and initialize the buffer */ ibuf = (FBFR32 *)tpal loc("FML32", NULL, 4000); obuf = (FBFR32 *)tpalloc("FML32", NULL, 4000); /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0); Fchg32(ibuf, TA_STATE, 0, "NEW", 0); /* Set TM_MIB(5) attributes to be set in T_DOMAIN class object */ Fchg32(ibuf, TA_OPTIONS, 0, "LAN,MIGRATE", 0); Fchg32(ibuf, TA_IPCKEY, 0, (char *)&ipckey, 0); Fchg32(ibuf, TA_MASTER, 0, "LMID1", 0); Fchg32(ibuf, TA_MODEL, 0, "MP", 0); /* Set TM_MIB(5) attributes for TA_MASTER T_MACHINE class object */ Fchg32(ibuf, TA_LMID, 0, "LMID1", 0); Fchg32(ibuf, TA_PMID, 0, pmid[0], 0); Fchg32(ibuf, TA_TUXCONFIG, 0, tuxconfig[0], 0); Fchg32(ibuf, TA_TUXDIR, 0, tuxdir[0], 0); Fchg32(ibuf, TA_APPDIR, 0, appdir[0], 0); Fchg32(ibuf, TA_ENVFILE, 0, envfile[0], 0); Fchg32(ibuf, TA_ULOGPFX, 0, ulogpfx[0], 0); Fchg32(ibuf, TA_BRIDGE, 0, "/dev/tcp", 0); Fchg32(ibuf, TA_NADDR, 0, naddr[0], 0); Fchg32(ibuf, TA_NLSADDR, 0, nlsaddr[0], 0); /* Perform the action via tpadmcall() */ if (tpadmcall(ibuf, obuf, 0) 0) { fprintf(stderr, "tpadmcall failed: %s\n", tpstrerror(tperrno)); /* Additional error case processing */ }

The following code reuses the buffers allocated in the previous section to build a request buffer. The request shown below adds a second machine to the configuration established earlier.

/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf)); /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_MACHINE", 0); Fchg32(ibuf, TA_STATE, 0, "NEW", 0); /* Set TM_MIB(5) attributes to be set in T_MACHINE class object */ Fchg32(ibuf, TA_LMID, 0, "LMID2", 0); Fchg32(ibuf, TA_PMID, 0, pmid[1], 0); Fchg32(ibuf, TA_TUXCONFIG, 0, tuxconfig[1], 0); Fchg32(ibuf, TA_TUXDIR, 0, tuxdir[1], 0); Fchg32(ibuf, TA_APPDIR, 0, appdir[1], 0); Fchg32(ibuf, TA_ENVFILE, 0, envfile[1], 0); Fchg32(ibuf, TA_ULOGPFX, 0, ulogpfx[1], 0); Fchg32(ibuf, TA_BRIDGE, 0, "/dev/tcp", 0); Fchg32(ibuf, TA_NADDR, 0, naddr[1], 0); Fchg32(ibuf, TA_NLSADDR, 0, nlsaddr[1], 0);  tpadmcall(...) /* See earlier example for detailed error processing */

The existing buffers are again reused to identify the newly configured second machine as the backup master site for this application.

/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));  /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0);  /* Set TM_MIB(5) T_DOMAIN attributes changing */ Fchg32(ibuf, TA_MASTER, 0, "LMID1,LMID2", 0);  tpadmcall(...); /* See earlier example for detailed error processing */

Reuse the buffers to generate two requests, each adding one server group to the configured application. Note how the second request simply modifies the necessary fields in the existing input buffer.

/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));  /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_GROUP", 0); Fchg32(ibuf, TA_STATE, 0, "NEW", 0);  /* Set TM_MIB(5) attributes defining first group */ Fchg32(ibuf, TA_SRVGRP, 0, "GRP1", 0); Fchg32(ibuf, TA_GRPNO, 0, (char *)&grpno[0], 0); Fchg32(ibuf, TA_LMID, 0, "LMID1,LMID2", 0);  tpadmcall(...); /* See earlier example for detailed error processing */  /* Set TM_MIB(5) attributes defining second group */ Fchg32(ibuf, TA_SRVGRP, 0, "GRP2", 0); Fchg32(ibuf, TA_GRPNO, 0, (char *)&grpno[1], 0); Fchg32(ibuf, TA_LMID, 0, "LMID2,LMID1", 0);  tpadmcall(...); /* See earlier example for detailed error processing */

Reuse the allocated buffers to add one server per group to the configured application.

/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));  /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_SERVER", 0); Fchg32(ibuf, TA_STATE, 0, "NEW", 0);  /* Set TM_MIB(5) attributes defining first server */ Fchg32(ibuf, TA_SRVGRP, 0, "GRP1", 0); Fchg32(ibuf, TA_SRVID, 0, (char *)&srvid[0], 0); Fchg32(ibuf, TA_SERVERNAME, 0, "ECHO", 0);  tpadmcall(...); /* See earlier example for detailed error processing */  /* Set TM_MIB(5) attributes defining second server */ Fchg32(ibuf, TA_SRVGRP, 0, "GRP2", 0); Fchg32(ibuf, TA_SRVID, 0, (char *)&srvid[1], 0);  tpadmcall(...); /* See earlier example for detailed error processing */

Add a routing criteria definition. Note that routing criteria may be dynamically added to a running application using a similar operation via the tpcall(3c) interface.

/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));  /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_ROUTING", 0); Fchg32(ibuf, TA_STATE, 0, "NEW", 0);  /* Set TM_MIB(5) attributes defining routing criteria */ Fchg32(ibuf, TA_ROUTINGNAME, 0, "ECHOROUTE", 0); Fchg32(ibuf, TA_BUFTYPE, 0, "FML", 0); Fchg32(ibuf, TA_FIELD, 0, "LONG_DATA", 0); Fchg32(ibuf, TA_RANGES, 0, "MIN-100:GRP1,100-MAX:GRP2", 26);  tpadmcall(...); /* See earlier example for detailed error processing */

Define a service object that maps the advertised service name to the routing criteria defined above.

/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));  /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_SERVICE", 0); Fchg32(ibuf, TA_STATE, 0, "NEW", 0);  /* Set TM_MIB(5) attributes defining service entry */ Fchg32(ibuf, TA_SERVICENAME, 0, "ECHO", 0); Fchg32(ibuf, TA_ROUTINGNAME, 0, "ECHOROUTE", 0);  tpadmcall(...); /* See earlier example for detailed error processing */

Activate the master site administrative processes (DBBL, BBL, BRIDGE) by setting the T_DOMAIN class object state to ACTIVE.

/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));  /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0); Fchg32(ibuf, TA_STATE, 0, "ACT", 0);  tpadmcall(...); /* See earlier example for detailed error processing */

Now that the application is active, we need to join the application and make our /AdminAPI requests via the tpcall(3c) interface.

/* Now that the system is active, join it as the administrator */ tpinfo = (TPINIT *)tpalloc("TPINIT", NULL, TPINITNEED(0)); sprintf(tpinfo->usrname, "appadmin"); sprintf(tpinfo->cltname, "tpsysadm"); if (tpinit(tpinfo) < 0) { fprintf(stderr, "tpinit() failed: %s\n", tpstrerror(tperrno)); /* Additional error case processing */ }  /* Reinitialize buffers as typed buffers */ Finit32(ibuf, Fsizeof32(ibuf)); Finit32(obuf, Fsizeof32(obuf));

Activate the remaining portions of the application. Note that the administrative user may request unsolicited notification messages be sent just before and just after the attempted boot of each server by setting the TMIB_NOTIFY flag in the TA_FLAGS attribute of the request. This example shows handling of an error return from tpcall(3c).

/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));  /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_MACHINE", 0); Fchg32(ibuf, TA_STATE, 0, "RAC", 0);  /* Set TM_MIB(5) attributes identifying machine */ Fchg32(ibuf, TA_LMID, 0, "LMID1", 0);  /* Invoke the /AdminAPI and interpret results */ if (tpcall(".TMIB", (char *)ibuf, 0, (char **)&obuf, &olen, 0) < 0) { fprintf(stderr, "tpcall failed: %s\n", tpstrerror(tperrno)); if (tperrno == TPESVCFAIL) { Fget32(obuf,TA_ERROR,0,(char *)&ta_error,NULL); ta_status = Ffind32(obuf, TA_STATUS, 0, NULL); fprintf(stderr, "Failure: %ld, %s\n", ta_error, ta_status); } /* Additional error case processing */ }

Generate a query on the status of one of the activated servers.

/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));  /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "GET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_SERVER", 0); flags = MIB_LOCAL; Fchg32(ibuf, TA_FLAGS, 0, (char *)&flags, 0);  /* Set TM_MIB(5) attributes identifying machine */ Fchg32(ibuf, TA_SRVGRP, 0, "GRP1", 0); Fchg32(ibuf, TA_SRVID, 0, (char *)&srvid[0], 0);  tpcall(...); /* See earlier example for detailed error processing */

Deactivate the application by setting the state of each machine to INACTIVE. Note that the TMIB_NOTIFY flag could be used with this operation also.

/* Clear the request buffer */ Finit32(ibuf, Fsizeof32(ibuf));  /* Shutdown Remote Machine First */ /* Set MIB(5) attributes defining request type */ Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_MACHINE", 0); Fchg32(ibuf, TA_LMID, 0, "LMID2", 0); Fchg32(ibuf, TA_STATE, 0, "INA", 0);  tpcall(....); /* See earlier example for detailed error processing */  /* And now application servers on master machine */ flags = TMIB_APPONLY; Fchg32(ibuf, TA_FLAGS, 0, (char *)&flags, 0); Fchg32(ibuf, TA_LMID, 0, "LMID1", 0);  tpcall(...); /* See earlier example for detailed error processing */  /* Terminate active application access */ tpterm();  /* Finally, shutdown the master admin processes */ Finit32(ibuf, Fsizeof32(ibuf)); Fchg32(ibuf, TA_OPERATION, 0, "SET", 0); Fchg32(ibuf, TA_CLASS, 0, "T_DOMAIN", 0); Fchg32(ibuf, TA_STATE, 0, "INA", 0);  tpadmcall(...); /* See earlier example for detailed error processing */

${TUXDIR}/include/tpadm.h, ${TUXDIR}/udataobj/tpadm

tpacall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c), Fintro(3fml), Fadd32(3fml), Fchg32(3fml), Ffind32(3fml), MIB(5), WS_MIB(5), BEA Tuxedo Administrator's Guide, BEA Tuxedo Programmer's Guide