|
|
|
|
|
|
MIB(5)
Name
MIB - Management Information Base
#include <fml32.h>
#include <fml1632.h> /* Optional */
#include <tpadm.h>
#include cmib.h> /* Component MIB Header */
Description
A BEA Tuxedo system application consists of distinct components (for example, BEA Tuxedo, Workstation), each administered using a Management Information Base (MIB) defined specifically for that component. These component MIBs are defined in individual reference pages each addressing the MIB for a particular part of the system. For example, the reference page TM_MIB(5) defines the MIB used to administer the fundamental aspects of a BEA Tuxedo application.
However, component MIBs do not provide sufficient definition of the interfaces involved to provide the necessary access. This reference 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 BEA Tuxedo system MIB consists of two main parts.
The first part of the generic interface is a description of how existing BEA Tuxedo system interfaces are used to provide access to administrative services responsible for supporting the component MIBs. FML32, a BEA 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 FML32and ATMI sections later in this reference 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 reference 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 reference page establishes the format used in the component MIB reference pages to define classes (see Class Descriptions).
Two generic classes are defined in this reference 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:
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 BEA 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() or tpsvrdone() are treated as coming from the administrator.
FML32
Application administration using BEA 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() and summarized here.
The most direct way to interface to FML32 is to include the <fml32.h> header file instead of the standard <fml.h> header file and then to use the FML32 version of each relevant FML interface specified in the BEA Tuxedo FML Function Reference. For example, one would use Fchg32() instead of using Fchg().
Another method for interfacing with FML32 is to include both the <fml32.h> header file and the <fml1632.h> header file. These two header files work together to allow the user to program to the base FML interfaces (for example, Fchg()) 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 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.
Input
There are certain FML32 fields used to characterize and control administrative requests to any BEA Tuxedo system MIB. These fields are defined in this reference page as well as in the header file <tpadm.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.
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 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 reference 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 <tpadm.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.
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() or tpgetrply(). 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.
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, then 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, 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.
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, 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, 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(), then a successful return from tpcall() indicates that the reply has been received. If the original request was generated using tpacall(), then 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, then 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:
Class name.
Number of matching objects retrieved.
Number of matching objects left to be retrieved.
Cursor to be provided on subsequent retrieval.
Set to the non-negative return value TAOK.
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:
Class name.
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.
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:
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. Field identifier of the offending field. Textual description of error condition.
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:
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:
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 BEA Tuxedo system application. Its primary use is to identify class names.
Attribute Table
|
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. |
Limitations
None identified.
T_CLASSATT Class Definition
Overview
The T_CLASSATT class represents characteristics of administrative attributes on a class/attribute basis.
Attribute Table
|
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. |
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(), tpgetrply() and tpdequeue()) used to retrieve responses to administrative requests may return any error defined on their respective reference 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() or tpgetrply() 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.
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.
Interoperability
Access to the FML32 interfaces, and therefore to the component MIBs available for administration of a BEA Tuxedo system application, are available on BEA Tuxedo Release 4.2.2 and later. The header files and field tables defining generic MIB attributes are available on BEA Tuxedo Release 5.0 and later. Interoperability concerns specific to a particular component MIB are discussed in the reference page for that component MIB.
Portability
The existing FML32 and ATMI functions necessary to support administrative interaction with BEA Tuxedo system MIBs, as well as the header file and field table defined in this reference page, are available on all supported native and workstation platforms.
Examples
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 reference page that make use of real component MIB classes and attributes.
Files
${TUXDIR}/include/tpadm.h,
${TUXDIR}/udataobj/tpadm See Also
tpacall(3c), tpalloc(3c), tpcall(3c), tpdequeue(3c), tpenqueue(3c), tpgetrply(3c), tprealloc(3c), Introduction to FML Functions, Fadd, Fadd32(3fml), Fchg, Fchg32(3fml), Ffind, Ffind32(3fml), AUTHSVR(5), TM_MIB(5), TMQFORWARD(5)
Setting Up a BEA Tuxedo Application
Administering a BEA Tuxedo Application at Run Time
Programming a BEA Tuxedo Application Using C
Programming a BEA Tuxedo Application Using FML
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|