Section 5 - File Formats, Data Descriptions, MIBs, and System Processes Reference

File Formats, Data Descriptions, MIBs, and System Processes Reference

Usage

Include Files

Application programs written to interface with component MIBs must include certain header files. <fml32.h> defines macros, structures and function interfaces necessary for accessing and updating FML32 typed buffers. <fml1632.h> defines a mapping from the generic FML interface macros, structures and functions to the FML32 versions and may optionally be included. <tpadm.h> defines the FML32 field names contained in this reference 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 <fml32.h>
#include <tpadm.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() allocates the buffer using FMLTYPE32 (defined in <fml32.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() and Fchg32(). In the event that a field cannot be added because the request buffer is full, the buffer may need to be reallocated using the ATMI verb tprealloc().

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 reference 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 reference pages. If TA_OPERATION is GETNEXT, 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

Used to specify flag values. Some generic flags are defined in this reference page; others are defined in each component MIB reference 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, n, 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, n, 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, 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, n, 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, n, 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 BEA Tuxedo 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(), tpacall() and tpenqueue(). 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() or tpacall() to direct administrative requests within a transaction, the TPNOTRAN flag should be used or the user will get a failure (TPETRAN). When using tpenqueue() 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, rpbuf, rplen, 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", qctl, 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(), a successful return from tpcall() indicates that the reply has been received. If the original request was generated using tpacall(), the reply may be received using tpgetrply(). If the original request was generated using tpenqueue() and a reply queue was specified in the queue control structure, the reply may be received using tpdequeue(). 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, rpbuf, rplen, flags);
/* Receive reply using call descriptor */
flags = TPNOCHANGE | TPSIGRSTRT;
rval = tpgetrply(cd, rpbuf, rplen, flags);
/* Receive reply using TPGETANY, may need to change buffer type */
flags = TPGETANY | TPSIGRSTRT;
rval = tpgetrply(rd, rpbuf, rplen, flags);
/* Dequeue reply, assumes qctl already setup */
flags = TPNOCHANGE | TPSIGRSTRT;
rval = tpdequeue("queue", "replyq", qctl, rpbuf, rplen, 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 reference 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 reference page. Component MIB specific error codes (non-overlapping, both with each other and with the generic codes) are specified on each MIB reference 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 (NULL) 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() or tpacall() 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() 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(), which returns the FML32 define representing the data type; that is, FLD_LONG, FLD_CHAR and FLD_STRING (see Fldtype, Fldtype32(3fml).

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 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 lowercase. Input TA_STATE values may be in either shorthand or long notation and are case insensitive. Output TA_STATE values are always full length uppercase. 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