PURPOSE

MIB - TUXEDO System Management Information Base

SYNOPSIS


#include &ltfml32.h>
#include &ltfml1632.h>   /* Optional */
#include &lttpadm.h>
#include <cmib.h>      /* Component MIB Header */

DESCRIPTION

A TUXEDO System application consists of distinct components (for example, System/T, /WS), each administered using a Management Information Base (MIB) defined specifically for that component. These component MIBs are defined in individual manual pages each addressing the MIB for a particular part of the system. For example, the manual page TM_MIB(5) defines the MIB used to administer the fundamental aspects of a System/T application.

However, component MIBs do not provide sufficient definition of the interfaces involved to provide the necessary access. This manual page, MIB(5), describes the generic interfaces through which an administrator, operator or user interacts with any of the defined component MIBs. The generic interface to each TUXEDO System MIB consists of two main parts.

The first part of the generic interface is a description of how existing TUXEDO System interfaces are used to provide access to administrative services responsible for supporting the component MIBs. FML32, a TUXEDO System buffer type, is used as the vehicle for passing input to and receiving output from component MIBs. ATMI request/response verbs are used as the interface to component MIBs, which are implemented as system supplied services. Details on interaction between an administrative user and component MIBs using FML32 buffers ATMI verbs are provided in the "FML32" and "ATMI" sections later in this manual page.

The second part of the generic interface is the definition of additional input and output FML32 fields that are used in interactions with all component MIBs. The additional FML32 fields extend the power of requests (for example, by allowing operation codes to be specified) and add generic response attributes (for example, error codes and explanatory text). Details on additional FML32 fields are provided in the "INPUT" and "OUTPUT" sections found later in this manual page.

The "USAGE" section gives examples of the use of existing ATMI verbs and the additional FML32 fields as they might be used for administrative interaction with component MIBs.

In addition to defining how users interface with component MIBs to administer an application, this manual page establishes the format used in the component MIB manual pages to define classes (see "CLASS DESCRIPTIONS").

Two generic classes are defined in this manual page: T_CLASS and T_CLASSATT. These two classes are used to identify administrative classes and to tune class/attribute permissions.

Finally, the "DIAGNOSTICS" section lists error codes that may be returned by component MIB system services.

AUTHENTICATION

Users are authenticated as they attempt to join the application (see tpinit(3c)). At tpinit time, administrators and operators can ask to join the application with a client name of either tpsysadm or tpsysop. These two cltname values are reserved and can only be associated with administrators and operators of the application.

The administrator who initially configures an application determines the level of security to be included by choosing a particular security type. Available security types are:

no security

application password authentication

application password plus an application specific authentication service

The choice of security type determines the flexibility and security in allowing administrator and operator access to the component MIBs via the AdminAPI.

The most secure and flexible security type is an application password plus an application-specific authentication server (see AUTHSVR(5)). This method allows the administrator to permit access to any user or to only specified users provided they supply the appropriate password to the authentication server.

In the absence of an application specific authentication server, a client must satisfy the authentication requirements of the application (either none or application password), specify one of the special client names in the cltname field of the TPINIT structure and be running as the TUXEDO administrator for the local UNIX System to qualify for special administrator or operator permissions. In any case, a successfully joined client is assigned a key by the system; the key is delivered with all requests it makes. Clients properly authenticated as either tpsysadm or tpsysop are assigned an authentication key that lets the system know they have special privileges.

Administrative authentication, as specified, is applicable only to clients that join the system prior to accessing the API. Servers making use of the API are treated the same as the client on whose behalf they are processing. Service requests made from within tpsvrinit(3c) or tpsvrdone(3c) are treated as coming from the administrator.

FML32

Application administration using TUXEDO System defined component MIBs is supported exclusively through the FML32 buffer type. Application programs accessing MIB information must be written to allocate, manipulate and update FML32 typed buffers. There are two main approaches to using FML32 as detailed in Fintro(3fml) and summarized here.

The most direct way to interface to FML32 is to include the &ltfml32.h> header file instead of the standard &ltfml.h> header file and then to use the FML32 version of each relevant FML interface specified in the TUXEDO Reference Manual. For example, one would use Fchg32(3fml) instead of using Fchg(3fml).

Another method for interfacing with FML32 is to include both the &ltfml32.h> header file and the &ltfml1632.h> header file. These two header files work together to allow the user to program to the base FML interfaces (for example, Fchg(3fml)) and yet actually invoke the FML32 version of each interface.

ATMI

Application programs access and update component MIB specific attribute information by allocating FML32 typed buffers, populating them with request data, sending the requests for servicing, receiving the replies to the service requests and extracting information regarding the results from the reply. The population and extraction of information to and from the FML32 typed buffers involves the FML32 interfaces as described above. Buffer allocation, sending requests and receiving replies is done using the general purpose ATMI routines listed below within the guidelines and restrictions listed. MIB requests for all components should be sent to the core System/T component MIB service, ".TMIB". This service not only acts as an agent for servicing TM_MIB(5) requests, it also directs requests targeted for other component MIBs so that the user need not be concerned with matching service names to MIBs and classes.

tpalloc
Allocate FML32 typed buffers to be used in sending requests and/or receiving replies to/from TUXEDO System MIB services. The FML32 buffer type has no subtypes and a minimum default size of 1024 bytes.
 
tprealloc
Reallocate FML32 typed buffers.
 
tpcall
Call TUXEDO System MIB service, ".TMIB", with a populated FML32 typed buffer as input and with an allocated FML32 typed buffer in which to store the output returned from the service. The buffer length for the input buffer may be specified as 0 since FML32 is a self-describing buffer type. The TPNOTRAN flag should be used if the call is being made within a transaction; otherwise, there are no specific requirements or restrictions on the use of the flags defined for this verb.
 
tpacall
Asynchronously call TUXEDO System MIB service, ".TMIB", with a populated FML32 typed buffer as input. The buffer length for the input buffer may be specified as 0 since FML32 is a self-describing buffer type. The TPNOTRAN flag should be used if the call is being made within a transaction; otherwise, there are no specific requirements or restrictions on the use of the flags defined for this verb.
 
tpgetrply
Get reply for a previously generated asynchronous call to the TUXEDO System MIB service, ".TMIB". The reply is received into a previously allocated FML32 typed buffer. There are no specific requirements or restrictions on the use of the flags defined for this verb.
 
tpenqueue
Enqueue a request to the TUXEDO System MIB service, ".TMIB", for later processing. The buffer length for the input buffer may be specified as 0 since FML32 is a self-describing buffer type. There are no specific requirements or restrictions on the use of the flags defined for this verb; however, the TMQFORWARD(5) server configured by the application to handle forwarding of these requests should be started with the -n ( tpcall() with TPNOTRAN flag set) and -d (delete) options.
 
tpdequeue
Dequeue the reply for a previously enqueued request to the TUXEDO System MIB service, ".TMIB". The reply is received into a previously allocated FML32 typed buffer. There are no specific requirements or restrictions on the use of the flags defined for this verb.

INPUT

There are certain FML32 fields used to characterize and control administrative requests to any TUXEDO System MIB. These fields are defined in this manual page as well as in the header file &lttpadm.h>. The corresponding field table file can be found in ${TUXDIR}/udataobj/tpadm. These fields are added to an FML32 request buffer in addition to any component MIB specific fields necessary before making the administrative service request. The fields are described below and followed by a table summarizing the operations for which each field is required, optional or unused.

TA_OPERATION
String valued field identifying the operation to be performed. Valid operations are GET, GETNEXT and SET.
 
TA_CLASS
String valued field identifying the class being accessed. Class names are defined within component MIB specific manual pages.
 
TA_CURSOR
String valued FML32 field returned by the system on a previous GET or GETNEXT operation. The value returned must be transferred by the application to the subsequent request buffer so that the system can determine current retrieval position.
 
TA_OCCURS
Long valued FML32 field identifying how many objects are to be retrieved on a GET or GETNEXT operation. If this field is not specified, then all matching objects are returned, space permitting.
 
TA_FLAGS
Long valued FML32 field identifying generic and component MIB specific flag values. Component MIB specific values that may be set in this attribute are defined within each component MIB manual page. Generic flag values and uses are listed below.
MIB_LOCAL
This flag is used to modify retrievals from certain classes defined in this MIB. For a number of classes in this MIB, there exists both global information (available at any site in an active application) and local information (available on the particular site where the object is active). Requests to retrieve information from these classes will by default retrieve only the global information and not the local for efficiency. If the application user is willing to wait for local information to be collected, possibly from multiple sites, then this flag should be set on the retrieval request. Classes with local information have local attributes listed last in the attribute table with a subheading indicating that they are local attributes. Classes which have only local information will automatically default to retrieving local information even if this flag value is not set.
 
MIB_PREIMAGE
indicates that a pre-image check must be passed before a SET operation will be performed. A pre-image check insures that occurrence 0 of any MIB specific class attributes match the existing object. If so, then the object is updated using occurrence 1 of any MIB specific class attributes. Attributes occurring less than two times are not considered for pre-image checking. Multiply occurring fields are checked if their associated count attribute is specified twice.
 
MIB_SELF
This flag is used as a shorthand to indicate that identification attributes for the client or server originating the request should be added to the request buffer prior to processing. For clients, TA_CLIENTID is added and for servers, TA_GRPNO and TA_SRVID are added.
TA_FILTER
Long valued FML32 field that may be specified with up to 32 occurrences to indicate the specific class attributes that should be returned. An occurrence with the value 0 may be specified to end the list but is not required. A list with an initial attribute value of 0 will return no class specific attributes but will return a count of class objects matched.
 
TA_MIBTIMEOUT
Long valued FML32 field identifying the time, in seconds, that should be allowed within the component MIB service to satisfy the request. A value less than or equal to 0 indicates that the component MIB service should not undertake any blocking operation. If unspecified, this value defaults to 20.
 
TA_CURSORHOLD
Long valued FML32 field identifying the time, in seconds, that a system snapshot generated from an initial GET operation should be held after the current GET or GETNEXT operation is satisfied before disposing of it. A value less than or equal to 0 indicates that the snapshot should be disposed of after satisfying the current request. If unspecified, this value defaults to 120.

In the following table, R indicates a required INPUT attribute, O an optional INPUT attribute, and -- an unused INPUT attribute.

Attribute Type GET GETNEXT SET
TA_OPERATION string R R R
TA_CLASS string R -- R
TA_CURSOR string -- R --
TA_OCCURS long O O --
TA_FLAGS long O O O
TA_FILTER long O -- --
TA_MIBTIMEOUT long O O O
TA_CURSORHOLD long O O --

OUTPUT

Output from successful administrative requests consists of one or more MIB specific objects and one occurrence of the generic output fields. In general, multiple MIB specific objects are reflected in the output buffer by multiple occurrences of each class attribute returned. Occurrence 0 of each attribute relates to the first object, occurrence 1 to the second object, and so on. Exceptions to this guideline are noted in the component MIB manual pages. Intermediate occurrences without values for certain attributes may have FML32 defined NULL field values inserted as place holders. A successful SET operation returns a single object reflecting the object after the operation was performed. A successful GET or GETNEXT operation may return 0 or more occurrences depending on how many occurrences were requested (see TA_OCCURS below), how many occurrences were matched by the specified key fields and space limitations within the MIB specific system service.

It is important to note that not all attributes defined for any class may necessarily be returned for any request depending on object state, interoperating release environments and/or input request filters. Administrative programmers should avoid implicit dependencies on the presence of certain attributes in output buffers and should instead explicitly check for the presence of attribute values.

To repeat, the reply to a successfully processed administrative request includes certain generic fields that apply to all MIBs. The fields are defined in the header file &lttpadm.h>. The corresponding field table file can be found in ${TUXDIR}/udataobj/tpadm. The generic reply fields are added to a the reply buffer and returned with the component MIB specific fields. The generic reply fields are described below.

TA_CLASS
String valued field identifying the class represented in the reply buffer. Class names are defined within component MIB specific manual pages.
 
TA_OCCURS
Long valued FML32 field identifying how many objects are in the reply buffer.
 
TA_MORE
Long valued FML32 field identifying how many additional objects matching the request key fields are being held in a system snapshot for later retrieval. This field is not returned for SET operations.
 
TA_CURSOR
String valued FML32 field identifying the position within a system held snapshot. This field must be added to the request buffer for a subsequent GETNEXT operation. The value of this field should not be interpreted or modified by the application user. This field is not returned for SET operations.
 
TA_ERROR
Long valued FML32 field identifying a non-negative return code characterizing the successful return. Generic return codes and their meaning are defined below.
TAOK
the operation was successfully performed. No updates were made to the application.
 
TAUPDATED
an update was successfully made to the application.
 
TAPARTIAL
a partial update was successfully made to the application.

Administrative requests that fail within MIB specific system service processing return an application service failure to the application including the original request and generic fields used to characterize the error. Application service failures are indicated by a TPESVCFAIL error return from tpcall(3c) or tpgetrply(3c). Application service failures returned via the TMQFORWARD(5) server will appear on the error queue specified on the original request (assuming the -d option was specified on the server command line). Generic fields used to characterize failed administrative requests are listed below.

TA_ERROR
Long valued FML32 field identifying the particular error that occurred. Error codes may be generic in which case they are listed in the "DIAGNOSTICS" section of this manual page, or they may be specific to a component MIB, in which case they are described on the individual component MIB manual page.
 
TA_STATUS
String valued FML32 field providing a textual description of the error.
 
TA_BADFLD
Long valued FML32 field providing the field identifier of the offending field in cases where an error can be attributed to the value in a particular field. In cases where errors are caused by the combination of values in multiple fields, there may be multiple occurrences of this field.

USAGE

Include Files

Application programs written to interface with component MIBs must include certain header files. &ltfml32.h> defines macros, structures and function interfaces necessary for accessing and updating FML32 typed buffers. &ltfml1632.h> defines a mapping from the generic FML interface macros, structures and functions to the FML32 versions and may optionally be included. &lttpadm.h> defines the FML32 field names contained in this manual page. Additionally, any component MIB specific header files must be included to gain access to FML32 field definitions specific to that component MIB. 


Example:
    #include &ltfml32.h>
    #include &lttpadm.h>
    #include <cmib.h>      /* Component MIB Header */

Buffer Allocation

Interaction with a component MIB requires an FML32 typed buffer to carry the request to the service that acts on it. The ATMI verb tpalloc(3c) allocates the buffer using FMLTYPE32 (defined in &ltfml32.h>) as the value for the type argument. There is no subtype for FML32 buffers so the subtype argument of tpalloc can be NULL. The default minimum size for an FML32 buffer is 1024 bytes. Specifying 0 for the size argument of tpalloc results in a buffer of minimum size. If the user knows that a larger buffer is needed, it may be allocated by specifying a value larger than the system minimum for size. 


Example:
    rqbuf = tpalloc(FMLTYPE32, NULL, 0);

Building MIB Requests

Once an FML32 typed buffer is allocated, the user needs to populate it with both generic MIB field values and values specific to the component MIB being addressed. The most common interfaces used to add values to a request buffer are the FML verbs Fadd32(3fml) and Fchg32(3fml). In the event that a field cannot be added because the request buffer is full, then the buffer may need to be reallocated using the ATMI verb tprealloc(3c). 


Example:
    /*
     * Does not include error processing, bigger_size provided
     * by the user, not by the system.  Fchg32 used to insure that
     * field occurrence 0 is set if we are reusing a buffer.
     */
    if (Fchg32(rqbuf, TA_MIBFIELD, 0, "ABC", 0) == -1) {
        if (Ferror32 == FNOSPACE) {
            rqbuf = tprealloc(rqbuf, bigger_size);
            Fchg32(rqbuf, TA_MIBFIELD, 0, "ABC", 0);
        }
    }

Controlling MIB Requests

In addition to attributes specific to each component MIB, there are required and optional attributes defined in this manual page that control the operation requested of the component MIB.

The required generic attributes are TA_OPERATION and TA_CLASS.

TA_OPERATION specifies the operation to be performed on the MIB being accessed. Valid operations are GET, GETNEXT and SET.

TA_CLASS specifies the MIB class being accessed. Class names are defined within the component MIB manual pages. If TA_OPERATION is GETNEXT, then an additional attribute, TA_CURSOR, is required. TA_CURSOR is a field returned on a previous GET or GETNEXT operation. It is used by the system on the subsequent request to determine retrieval position.

The optional attributes TA_OCCURS, TA_FLAGS, TA_FILTER, TA_MIBTIMEOUT and TA_CURSORHOLD may be used in addition to the required attributes to further tailor the request.

TA_OCCURS
specifies how many objects are to be retrieved on a GET or GETNEXT operation. If unspecified, all occurrences are retrieved, space permitting.
 
TA_FLAGS
is used to specify flag values. Some generic flags are defined in this manual page; others are defined in each component MIB manual page.
 
TA_FILTER
restricts the attribute values returned for a GET operation. If unspecified, is a long valued FML32 field used to all available class attribute values are returned.
 
TA_MIBTIMEOUT
specifies the time, in seconds, that should be allowed within the component MIB service to satisfy the request. A value less than or equal to 0 indicates that the component MIB service should not undertake any blocking operation. If unspecified, this value defaults to 20.
 
TA_CURSORHOLD
specifies the time, in seconds, that a system snapshot generated from an initial GET operation should be held after the current GET or GETNEXT operation is satisfied before disposing of it. A value less than or equal to 0 indicates that the snapshot should be disposed of after satisfying the current request. If unspecified, this value defaults to 120. 

Example:
    /* GET 1st 5 objects */
    Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
    Fchg32(rqbuf, TA_CLASS, 0, "classname", 0);
    n = 5;
    Fchg32(rqbuf, TA_OCCURS, 0, &ampn, 0);
    /* Make request, see Sending MIB Requests below */
    /* Reply is stored in rpbuf and contains cursor */
    /*
     * GETNEXT 5 objects. Transfer TA_CURSOR from rpbuf.
     * Reuse rqbuf generated above.  Dispose of snapshot after
     * request, that is, set TA_CURSORHOLD to 0.
     */
    Fchg32(rqbuf, TA_OPERATION, 0, "GETNEXT", 0);
    Fchg32(rqbuf, TA_CURSOR, 0, Ffind32(rpbuf, TA_CURSOR, 0, NULL), 0);
    n = 0;
    Fchg32(rqbuf, TA_CURSORHOLD, 0, &ampn, 0);
    /* Make request, see Sending MIB Requests below */

Component MIB Fields

Component MIB key fields specified on a GET or GETNEXT are used to select a set of objects. Non-key fields are ignored by the component MIB.

Component MIB key fields specified on a SET operation are used to identify the particular object to be updated. Non-key fields are processed as updates to the object identified by the key fields. The user may optionally specify a pre-image which must match the current object image before an update (SET) is allowed. A user indicates that a pre-image is provided by setting the MIB_PREIMAGE bit in the TA_FLAGS attribute of the request. The key fields specifying the object to be updated are taken from the pre-image (field occurrence 0). If key fields are also specified in the post-image, then they must match exactly or the request fails. Only attributes that are part of the class and have two attribute values specified in the input buffer are considered for pre-image matching. Attributes with single values are processed as new values to be set for the indicated class object. 


Example:
    Fchg32(rqbuf, TA_OPERATION, 0, "GET", 0);
    Fchg32(rqbuf, TA_CLASS, 0, "classname", 0);
    Fchg32(rqbuf, TA_MIBKEY, 0, "keyvalue", 0);
    n = 1;
    Fchg32(rqbuf, TA_OCCURS, 0, &ampn, 0); /* GET 1st matching occurrence */
    /* Make request, see Sending MIB Requests below, reply in rpbuf */
    /* Use rpbuf as pre-image and update TA_MIBFIELD value if matching */
    Fcpy32(newrq, rpbuf);
    Fconcat32(newrq, rpbuf);	/* Add 2nd identical copy */
    Fchg32(newrq, TA_OPERATION, 0, "SET", 0);
    n = MIB_PREIMAGE;
    Fchg32(newrq, TA_FLAGS, 0, &ampn, 0);
    Fchg32(newrq, TA_MIBFIELD, 1, "newval", 0); /* Post-image */
    /* Make request, see Sending MIB Requests below */

Sending MIB Requests

All component MIB requests flow through the core System/T component MIB service, ".TMIB". This service not only acts as an agent for servicing TM_MIB(5) requests, it also directs requests targeted for other component MIBs so that the user need not be concerned with matching service names to MIBs and classes. Service requests can be generated using any of the request/response oriented service verbs in ATMI: tpcall(3c), tpacall(3c) and tpenqueue(3c). The user has access to all flags and capabilities defined for these interface functions. The only constraint imposed here is that the ".TMIB" service must be invoked outside the scope of any transaction. This means that when using tpcall(3c) or tpacall(3c) to direct administrative requests within a transaction, the TPNOTRAN flag should be used or the user will get a failure (TPETRAN). When using tpenqueue(3c) to direct requests, the TMQFORWARD server must be started with the -n option so that the forwarded service requests may be made outside of transactional boundaries. 


Example:
    /* Build request as shown above */
    /* Send request and wait for reply */
    flags = TPNOTRAN | TPNOCHANGE | TPSIGRSTRT;
    rval = tpcall(".TMIB", rqbuf, 0, &amprpbuf, &amprplen, flags);
    /* Send request and get descriptor back */
    flags = TPNOTRAN | TPSIGRSTRT;
    cd = tpacall(".TMIB", rqbuf, 0, flags);
    /* Enqueue request, assumes qctl already setup */
    flags = TPSIGRSTRT;
    rval = tpenqueue("queue", ".TMIB", &ampqctl, rqbuf, 0, flags);

Receiving MIB Replies

Replies from component MIBs may be received in one of three ways depending on how the original request was generated. If the original request was generated using tpcall(3c), then a successful return from tpcall(3c) indicates that the reply has been received. If the original request was generated using tpacall(3c), then the reply may be received using tpgetrply(3c). If the original request was generated using tpenqueue(3c) and a reply queue was specified in the queue control structure, then the reply may be received using tpdequeue(3c). All supported flags on these various calls may be used as appropriate. 


Example:
    /* Build request as shown above */
    /* Send request and wait for reply */
    flags = TPNOTRAN | TPNOCHANGE | TPSIGRSTRT;
    rval = tpcall(".TMIB", rqbuf, 0, &amprpbuf, &amprplen, flags);
    /* Receive reply using call descriptor */
    flags = TPNOCHANGE | TPSIGRSTRT;
    rval = tpgetrply(&ampcd, &amprpbuf, &amprplen, flags);
    /* Receive reply using TPGETANY, may need to change buffer type */
    flags = TPGETANY | TPSIGRSTRT;
    rval = tpgetrply(&amprd, &amprpbuf, &amprplen, flags);
    /* Dequeue reply, assumes qctl already setup */
    flags = TPNOCHANGE | TPSIGRSTRT;
    rval = tpdequeue("queue", "replyq", &ampqctl, &amprpbuf, &amprplen, flags);

Interpreting MIB Replies

In addition to attributes specific to a component MIB certain generic MIB fields may be returned in response to an administrative request, These additional attributes characterize the results of the original request and provide values that can be used in subsequent requests if necessary.

Successful GET or GETNEXT operations return:

TA_CLASS
Class name.
 
TA_OCCURS
Number of matching objects retrieved.
 
TA_MORE
Number of matching objects left to be retrieved.
 
TA_CURSOR
Cursor to be provided on subsequent retrieval.
 
TA_ERROR
Set to the non-negative return value TAOK.
 
All available component MIB specific attributes
Occurrence 0 of each attribute represents the first retrieved object, occurrence 1 the second, and so on. Exceptions to this rule are identified as appropriate in the component MIB manual pages.

Successful SET operations return:

TA_CLASS
Class name.
 
TA_ERROR
Set to a non-negative return value. TAOK indicates that the request was successful but no information was updated. This can happen because no changes were specified or because the changes specified match the current state of the object. TAUPDATED indicates that the request was successful and the information was updated. TAPARTIAL indicates that the request was successful but the update was only made partially within the system. This may occur because of network failures or message congestion and the system will synchronize the unupdated sites as soon as possible.
 
All available component MIB specific attributes
Since only one object may be updated at once, only one object will be returned. The returned attributes reflect the object after the update.

Failed operations of any type return:

Fields specified on the original request
 
TA_ERROR
Set to a negative return value indicating the cause of the failure. Generic error codes are specified in the "DIAGNOSTICS" section of this manual page. Component MIB specific error codes (non-overlapping, both with each other and with the generic codes) are specified on each MIB manual page.
 
TA_BADFLD
Field identifier of the offending field.
 
TA_STATUS
Textual description of error condition.

LIMITATIONS

FML32 buffers with multiple occurrences of fields do not allow for empty fields in a sequence of occurrences. For example, if you set a value for occurrence 1 and occurrence 0 does not yet exist, FML32 automatically creates occurrence 0 with an FML32 defined NULL value. FML32 defined NULL values are 0 for numeric fields, 0-length strings for string fields and the character '\0' for character fields. Because of this limitation, GET operations, which may at times return objects with different sets of attributes, may artificially break up the sets of objects returned to the user so as to not include NULL FML32 fields that do not accurately reflect the state of the object.

Workstation clients on DOS, Windows and OS/2 are currently limited to 64K FML32 buffers; therefore, the system restricts return buffers to be less than 64K per buffer.

Administrative API access is not available through the COBOL version of ATMI since COBOL has limited support for FML32 buffer type.

Requests to any component MIB cannot be part of an application transaction. Therefore, any calls to tpcall(3c) or tpacall(3c) directed to a component MIB and made within an active transaction should set the TPNOTRAN flag on the call. However, requests may be enqueued for future delivery to a component MIB using the ATMI verb tpenqueue(3c) within a transaction. The enqueuing of the request will take place within a transaction while the processing within the component MIB will not. The use of the TMQFORWARD(5) server in this context requires that TMQFORWARD be started with the -n command line option so that request may be forwarded to the MIB service in non-transactional mode. Because of the non-transactional nature of component MIB services, it is also recommended that the -d option for TMQFORWARD be used so that service failures are delivered to the failure queue immediately rather than retrying the request.

Field identifiers for generic MIB fields and for component MIBs will be allocated in the range 6,000 to 8,000 inclusive. Therefore, applications which intend to mix administrative actions with user actions should make sure to allocate field identifiers appropriately.

CLASS DESCRIPTIONS

Each class description section has four subsections:

Overview
High level description of the attributes associated with the class.
 
Attribute Table
A table that lists the name, type, permissions, values and default for each attribute in the class. The format of the attribute table is described below.
 
Attribute Semantics
Tells how each attribute should be interpreted.
 
Limitations
Limitations in the access to and interpretation of this class.

Attribute Table Format

As described above, each class is defined in four parts. One part is the attribute table. The attribute table is a reference guide to the attributes within a class and how they may used by administrators, operators and general users to interface with an application. There are five components to each attribute description in the attribute tables: name, type, permissions, values and default. Each of these components is discussed in detail below:

Name:
FML32 field identifier name used to identify this attribute value within an FML32 buffer. Attributes may be arranged in groups of closely related attributes. No special meaning should be implied from the groupings; they are intended only to improve the usability of the table. A notation ( r ), ( k ), ( x ) or ( * ) may appear after an attribute name or value. The meaning of the notation is as follows: ( r ) - the field is required when a new object is created ( k ) - indicates a key field for object retrieval ( x ) - indicates a regular expression key field for object retrieval ( * ) - the field is a SET key for object modification SET operations on classes with one or more SET keys defined ( see * above) must include values for one or more of the attribute values defined as SET keys. The SET keys specified must be sufficient to identify exactly one object within the class. SET keys are always key fields for object retrieval and therefore the ( k ) notation is implied though not specified. SET keys are not however always required fields when creating NEW objects and will be marked with the ( r ) notation if they are required.
 
Type:
Data type of the attribute value. Data types are defined in C language notation, that is, long, char and string. In a program, data type can be determined by using the FML32 function Fldtype32(3) which returns the FML32 define representing the data type; that is, FLD_LONG, FLD_CHAR and FLD_STRING.
 
Permissions:
Access and update permissions are split into three groups of three each, in the manner of UNIX System permissions. However, in the attribute tables the three groups represent permissions for administrators, operators and others rather than for owner, group and others as is the case in UNIX. For each group there are three permissions positions that have the following meanings:
Position 1 - Retrieval permissions

r
Attribute may be retrieved.
 
R
Attribute may be retrieved only when the object state is ACTive or ACTive equivalent. See the description of the TA_STATE attribute value for each class to determine which states qualify as ACTive equivalent. This attribute represents transient information that is not persistent across distinct activations of the object.
 
k
Attribute may be specified only as a key field for retrieval or update.
 
K
Attribute may be specified only as a key field for retrieval or update and then only when the object state is ACTive or ACTive equivalent. See the description of the TA_STATE attribute value for each class to determine which states qualify as ACTive equivalent.
Position 2 - Inactive update permissions

w
Attribute may be updated when the object is in an INActive or INActive equivalent state. See the description of the TA_STATE attribute value for each class to determine which states qualify as INActive equivalent.
 
u
Attribute may be updated as described for the w permissions value. In addition, the combination of all attribute values identified with the u permissions character must be unique within the class.
 
U
Attribute may be updated as described for the w permissions value. In addition, the attribute value must be unique for the attribute within the class.
Position 3 - Active update permissions

x
Attribute may be updated when the object is in an ACTive or ACTive equivalent state. See the description of the TA_STATE attribute value for each class to determine which states qualify as ACTive equivalent.
 
X
Attribute may be updated when the object is in an ACTive or ACTive equivalent state. See the description of the TA_STATE attribute value for each class to determine which states qualify as ACTive equivalent. This attribute represents transient information and updates to this attribute value are not persistent across distinct activations of the object.
 
y
Attribute may be updated when the object is in an ACTive or ACTive equivalent state. However, there are limitations on when the change will affect objects of this or other classes. Consult the textual description of the attribute in the Attribute Semantics section for the class for more details. See the description of the TA_STATE attribute value for each class to determine which states qualify as ACTive equivalent.
 
Values:
Values that may be set and/or retrieved with respect to this attribute. Certain formatting conventions are followed in listing attribute values.
LITSTRING
Literal string value.
 
num
Numeric value.
 
string[x..y]
String value between x and y characters in length, not including the terminating NULL character.
 
LMID
Shorthand for string[1..30] (no commas allowed). Represents a logical machine identifier.
 
{x|y|z}
Select one of x, y or z.
 
[x|y|z]
Select zero or one of x, y or z.
 
[x|y|z],*
Zero or more occurrences of x, y or z in a comma-separated list.
 
low <= num
Numeric value greater than or equal to low.
 
low <= num high
Numeric value greater than or equal to low and less than high.
 
GET:
State attribute values that may be returned or specified as key values on a retrieve (GET) operation. Values shown are always the three letter state abbreviation. The expanded state name is shown in the text describing the TA_STATE for the class. Input specifications may be made in either the shorthand or expanded form and are case-insensitive. Output states are always returned in expanded format with all upper case.
 
SET:
State attribute values that may be set on an update (SET) operation. Use of abbreviations is allowed as described above.
 
Default:
Default value used when creating a new object, that is, state change from INValid to NEW. The value N/A is shown in this column for attributes that are required, derived or only available when the object is active.

TA_STATE Syntax

The TA_STATE attribute field is a member of each class defined. The semantics of this attribute are defined on a class by class basis. For the sake of brevity, TA_STATE values are often specified in a three character shorthand notation. When an expanded version of a TA_STATE value is shown, the three shorthand letters are capitalized and the rest of the letters (if any) are displayed in lower case. Input TA_STATE values may be in either shorthand or long notation and are case insensitive. Output TA_STATE values are always full length upper case. The following example should help clarify the use of the TA_STATE attribute. 


Full Name    : ACTive
Shorthand    : ACT
Output Value : ACTIVE
Valid Input  : ACT, act, AcTiVe, active

T_CLASS CLASS DEFINITION

Overview

The T_CLASS class represents attributes of administrative classes within a TUXEDO System application. Its primary use is to identify class names.

Attribute Table

MIB(5): T_CLASS Class Definition Attribute Table
Attribute Type Permissions Values Default
TA_CLASSNAME( k ) string r--r--r-- string N/A
TA_STATE( k ) string r--r--r-- GET:"{VAL}" GET:N/A
SET: N/A SET: N/A
TA_GETSTATES string r--r--r-- string N/A
TA_INASTATES string r--r--r-- string N/A
TA_SETSTATES string r--r--r-- string N/A

( k ) - a key field for object retrieval

Attribute Semantics

TA_CLASSNAME: string
Class name.
TA_STATE:
GET:
A GET operation retrieves information for the selected T_CLASS object(s). The following states indicate the meaning of a TA_STATE returned in response to a GET request. States not listed are not returned.
VALid
T_CLASS object is defined. All objects of this class exist in this state. This state is INActive-equivalent for the purposes of permissions checking.
SET:
SET operations are not permitted on this class.
TA_GETSTATES: string
Delimited list ('|' delimiter) of the states that may be returned for an object in this class or as the result of a GET operation. States are returned in their full length uppercase format.
 
TA_INASTATES: string
Delimited list ('|' delimiter) of the inactive equivalent states that may be returned for an object in this class or as the result of a GET operation. States are returned in their full length uppercase format.
 
TA_SETSTATES: string
Delimited list ('|' delimiter) of the states that may be set for an object in this class as part of a SET operation. States are returned in their full length uppercase format.

Limitations

None identified.

T_CLASSATT CLASS DEFINITION

Overview

The T_CLASSATT class represents characteristics of administrative attributes on a class/attribute basis.

Attribute Table

MIB(5): T_CLASSATT Class Definition Attribute Table
Attribute Type Permissions Values Default
TA_CLASSNAME( r )( * ) string ru-r--r-- string N/A
TA_ATTRIBUTE( r )( * ) long ru-r--r-- 0 <= num N/A
TA_STATE( k ) string rw-r--r-- GET:"{VAL}" GET: N/A
SET:"{NEW|INV}" SET: N/A
TA_PERM( r ) long rw-r--r-- 0000 <= num <= 0777 N/A
TA_FACTPERM long r--r--r-- 0000 <= num <= 0777 N/A
TA_MAXPERM long r--r--r-- 0000 <= num <= 0777 N/A
TA_ATTFLAGS long r--r--r-- long N/A
TA_DEFAULT string r--r--r-- string N/A
TA_VALIDATION string r--r--r-- string N/A

( k ) - GET key field

( r ) - Required field for object creation (SET TA_STATE NEW)

( * ) - GET/SET key, one or more required for SET operations

Attribute Semantics

TA_CLASSNAME : string
Class name. Only class names known to the system are accessible.
 
TA_ATTRIBUTE: long
Attribute field identifier as defined in the system provided header file, for example, tpadm.h.
 
TA_STATE :
GET: VALid
A GET operation will retrieve information for the selected T_CLASSATT 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.
VALid
T_CLASSATT object is defined. All objects of this class exist in this state. This state is INActive equivalent for the purposes of permissions checking.
 
SET: {NEW|INValid}
A SET operation will update configuration information for the selected T_CLASSATT object. The following states indicate the meaning of a TA_STATE set in a SET request. States not listed may not be set.
NEW
Create T_CLASSATT object for application. State change allowed only when in the INValid state. Successful return leaves the object in the VALid state.
 
unset
Modify T_CLASSATT object. Allowed only when in the VALid state. Successful return leaves the object state unchanged.
 
INValid
Delete or reset T_CLASSATT object for application. State change allowed only when in the VALid state. Successful return leaves the object in either the INValid state or the VALid state. Objects of this class that are built-in, that is, explicitly known to the system, will revert to their default permissions on this state change and continue to exist in the VALid state. Objects of this class that belong to add-on components for which the class attributes are not explicitly known will be deleted on this state change and transition to the INValid state.
TA_PERM : 0000 <= num <= 0777
Access permissions for this class attribute combination. When setting permissions, the actual value set may be automatically reset if the requested setting exceeds the permissions available for the attribute. The maximum permissions available for an attribute are the permissions documented for the administrator repeated in the operator and other permissions positions. For example, the TA_TYPE attribute of the T_MACHINE class is documented with permissions rw-r--r-- and has maximum permissions of rw-rw-rw-.
 
TA_FACTPERM : 0000 <= num <= 0777
Permissions for this class attribute combination as set on delivery of the TUXEDO System from the factory. These permissions will apply after a SET operation changing the TA_STATE of an object to INValid.
 
TA_MAXPERM : 0000 <= num <= 0777
Maximum permissions for this class attribute combination.
 
TA_ATTFLAGS : long
Bitwise or of none, some or all of the following flags indicating special characteristics of this attribute.
MIBATT_KEYFIELD
Attribute is a key field for this class.
 
MIBATT_LOCAL
Attribute represents local information.
 
MIBATT_REGEXKEY
Attribute is a regular expression key field for this class.
 
MIBATT_REQUIRED
Attribute is required when creating a NEW object in this class.
 
MIBATT_SETKEY
Attribute is a SET key for this class.
 
MIBATT_NEWONLY
NEW object by changing the TA_STATE from INValid to NEW.
 
TA_DEFAULT : string
Default value for this attribute when creating a NEW object in this class. Note that for classes where NEW objects may not be created through the Admin API, this attribute will always be returned as a 0 length string. Attributes that may not be SET when creating a NEW object are also returned as 0 length strings. Attributes which have long values will have default values returned as the string representing the long value. Some attributes have special characteristics indicated by the special values indicated below that may be returned here.
# Inherited:Classname[:Attribute]
Attribute default is inherited from the attribute of the same name in the indicated class. If Attribute is specified, then the value is inherited from the indicated attribute rather than the one of the same name.
 
# Required
Attribute is required when creating a NEW object.
 
# Special
Attribute has special rules for defining the default value. The appropriate component MIB manual page should be consulted for further details.
TA_VALIDATION : string
String representing the validation rule applied to this class/attribute combination when a new value is being SET. This string will take one of the following formats:
CHOICES=string1|string2|...
String attribute value that must match exactly one of the choices shown.
RANGE=min--max
Numeric attribute value that must be between min and max, inclusive.
 
SIZE=min--max
String or carray attribute value that must have a length between min and max bytes long, inclusive.
 
READONLY=Y
Readonly attribute with no validation rule for write operations.
 
SPECIAL=Y
Special validation rule. Consult the appropriate component MIB manual page for more details.
 
UNKNOWN=Y
Unknown validation rule. Commonly associated with add-on component attribute entries for which the details are not known by the core system.

Limitations

None identified.

DIAGNOSTICS

There are two general types of errors that may be returned to the user when interfacing with component MIBs. 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 on their respective manual pages.

Second, if 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) or tpgetrply(3c) returns an error with tperrno set to TPESVCFAIL and returns a reply message containing the original request along with TA_ERROR, TA_STATUS or 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, the FML32 field TA_ERROR is set to indicate the cause of the failure as indicated below. TA_BADFLD is set as indicated in the description of the individual errors below. All error codes specified below are guaranteed to be negative.

[TAEAPP]
The originating request required application cooperation to be successfully completed and the application did not allow the operation to be completed. For example, server shutdown requires application cooperation.
 
[TAECONFIG]
The configuration file associated with the component MIB could not be accessed as needed to satisfy the requested operation.
 
[TAEINVAL]
A specified field is invalid. TA_BADFLD is set to indicate the invalid field identifier.
 
[TAEOS]
An operating system error occurred while attempting to satisfy the request. TA_STATUS is updated with the translation of the system error code errno.
 
[TAEPERM]
An attempt was made to SET an attribute for which the user does not have write permissions or the user attempted a GET on a class for which the user does not have read permissions. TA_BADFLD is set to indicate the field identifier that failed permissions checking.
 
[TAEPREIMAGE]
A SET operation failed due to a mismatch between the specified pre-image and the current object. TA_BADFLD is set to indicate the field identifier that failed the pre-image checking.
 
[TAEPROTO]
The administrative request was made in an improper context. TA_STATUS is populated with additional information.
 
[TAEREQUIRED]
A required field value is not present. TA_BADFLD is set to indicate the missing field identifier.
 
[TAESUPPORT]
The administrative request is not supported in the current version of the system.
 
[TAESYSTEM]
A TUXEDO System error occurred while attempting to satisfy the request. TA_STATUS is updated with more information on the error condition.
 
[TAEUNIQ]
A SET operation did not specify class keys identifying a unique object to be updated.
 
[other]
Other error return codes specific to particular component MIBs are specified in the component MIB manual pages. These error codes are guaranteed to be mutually exclusive both amongst all component MIBs and with generic 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.

[TAOK]
The operation succeeded. No updates were done to the component MIB object(s).
 
[TAUPDATED]
The operation succeeded. Updates were made to the component MIB object.
 
[TAPARTIAL]
The operation partially succeeded. Updates were made to the component MIB object.

INTEROPERABILITY

Access to the FML32 interfaces, and therefore to the component MIBs available for administration of a TUXEDO System application, are available on TUXEDO System/T Release 4.2.2 and later. The header files and field tables defining generic MIB attributes are available on TUXEDO Release 5.0 and later. Interoperability concerns specific to a particular component MIB are discussed in the manual page for that component MIB.

PORTABILITY

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

EXAMPLES

See the "USAGE" section earlier for some brief example uses of existing APIs in interfacing with generic MIB processing. More detailed examples are provided with each component MIB manual page that make use of real component MIB classes and attributes.

FILES

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

SEE ALSO

Fintro(3fml),
Fadd32(3fml),
Fchg32(3fml),
Ffind32(3fml)
tpalloc(3c),
tprealloc(3c),
tpcall(3c),
tpacall(3c),
tpgetrply(3c),
tpenqueue(3c),
tpdequeue(3c)
AUTHSVR(5),
TM_MIB(5),
TMQFORWARD(5)
BEA TUXEDO Administrator's Guide
BEA TUXEDO Programmer's Guide