Section 3c - C Functions

ATMI C Function Reference

tpadmcall(3c)

Name

tpadmcall()—Administers unbooted application.

Synopsis

#include <atmi.h> 
#include <fml32.h> 
#include <tpadm.h> 
 
int tpadmcall(FBFR32 *inbuf, FBFR32 **outbuf, long flags)

Description

tpadmcall() is used to retrieve and update attributes of an unbooted application. It may also be used in an active application to perform direct retrievals of a limited set of attributes without requiring communication to an external process. This function provides sufficient capability such that complete system configuration and administration can take place through system provided interface routines.

inbuf is a pointer to an FML32 buffer previously allocated with tpalloc() that contains the desired administrative operation and its parameters.

outbuf is the address of a pointer to the FML32 buffer that should contain the results. outbuf must point to an FML32 buffer originally allocated by tpalloc(). If the same buffer is to be used for both sending and receiving, outbuf should be set to the address of inbuf.

Currently, tpadmcall()'s last argument, flags, is reserved for future use and must be set to 0.

MIB(5) should be consulted for generic information on construction of administrative requests. TM_MIB(5) and APPQ_MIB(5) should be consulted for information on the classes that are accessible through tpadmcall().

There are four modes in which calls to tpadmcall() can be made.

Mode 1: Unbooted, Unconfigured Application:

The caller is assumed to be the administrator of the application. The only operations permitted are to SET a NEW T_DOMAIN class object, thus defining an initial configuration for the application, and to GET and SET objects of the classes defined in APPQ_MIB().

Mode 2: Unbooted, Configured Application:

The caller is assigned administrator or other privileges based on a comparison of their UID/GID to that defined in the configuration for the administrator on the local system. The caller may GET and SET any attributes for any class in TM_MIB() and APPQ_MIB() for which they have the appropriate permissions. Note that some classes contain only attributes that are inaccessible in an unbooted application and attempts to access these classes will fail.

Mode 3: Booted Application, Unattached Process:

The caller is assigned administrator or other privileges based on a comparison of their UID/GID to that defined in the configuration for the administrator on the local system. The caller may GET any attributes for any class in TM_MIB() for which they have the appropriate permissions. Similarly, the caller may GET and SET any attributes for any class in APPQ_MIB(), subject to class-specific restrictions. Attributes accessible only while ACTIVE will not be returned.

Mode 4: Booted Application, Attached Process:

Permissions are determined from the authentication key assigned at tpinit() time. The caller may GET any attributes for any class in TM_MIB() for which they have the appropriate permissions. Additionally, the caller may GET and SET any attributes for any class in APPQ_MIB(), subject to class-specific restrictions.

Access to and update of binary BEA Tuxedo ATMI system application configuration files through this interface routine is controlled through the use of UNIX system permissions on directory names and filenames.

In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tpadmcall().

Environment Variables

The following environment variables must be set prior to calling this routine:

TUXCONFIG

Name of the file or device on which the binary BEA Tuxedo system configuration file for this application is or should be stored.

Notices

Use of the TA_OCCURS attribute on GET requests is not supported when using tpadmcall(). GETNEXT requests are not supported when using tpadmcall().

Return Values

tpadmcall() returns 0 on success and -1 on failure.

Errors

Upon failure, tpadmcall() sets tperrno to one of the following values:

Note: Except for TPEINVAL, the caller's output buffer, outbuf, will be modified to include TA_ERROR, TA_STATUS, and possibly TA_BADFLD attributes to further qualify the error condition. See MIB(5), TM_MIB(5), and APPQ_MIB(5) for an explanation of possible error codes returned in this fashion.

[TPEINVAL]

Invalid arguments were specified. The flags value is invalid or inbuf or outbuf are not pointers to typed buffers of type "FML32."

[TPEMIB]

The administrative request failed. outbuf is updated and returned to the caller with FML32 fields indicating the cause of the error as is discussed in MIB(5) and TM_MIB(5).

[TPEPROTO]

tpadmcall() was called improperly.

[TPERELEASE]

tpadmcall() was called with the TUXCONFIG environment variable pointing to a different release version configuration file.

[TPEOS]

An operating system error has occurred. A numeric value representing the system call that failed is available in Uunixerr.

[TPESYSTEM]

A BEA Tuxedo system error has occurred. The exact nature of the error is written to userlog().

Interoperability

This interface supports access and update to the local configuration file and bulletin board only; therefore, there are no interoperability concerns.

Portability

This interface is available only on UNIX system sites running BEA Tuxedo ATMI release 5.0 or later.

Files

The following library files are required:

${TUXDIR}/lib/libtmib.a, ${TUXDIR}/lib/libqm.a, ${TUXDIR}/lib/libtmib.so.<rel>, ${TUXDIR}/lib/libqm.so.<rel>, ${TUXDIR}/lib/libtmib.lib, ${TUXDIR}/lib/libqm.lib

The libraries must be linked manually when using buildclient. The user must use: -L${TUXDIR}/lib -ltmid -lqm