| Previous | Contents | Index |
The tables in Chapter 8 and the tables defined in the ACMS MIB map to each other on a one-to-one basis. However, data types are slightly different between SNMP and RPC, most significantly in the use of the gauge structure type. Section 6.4.1 describes data type mapping.
When accessing any of the ACMS MIB tables, it is important to keep in mind the dynamic nature of the ACMS run-time system. ACMS entities may be stopped and restarted; collection states for the entities may change dynamically; new processes (especially EXC and CPs) may be created. It is also important to understand that the size of some ACMS MIB tables may change when either the ACMS run-time system is restarted, or even as certain processes are started and stopped.
If the proper access strategies are not used when getting or setting ACMS MIB data, unpredictable and erroneous results can occur.
Different access strategies must be used for different types of tables. In the ACMS MIB, there are three types of tables. Specific access strategies for each table type are discussed in separate sections, as follows:
Also refer to Section 6.4.5 for a discussion of how the Server and Task Group tables are indexed.
Regardless of the type of table, identity and state validation should be performed for all ACMS entity tables (ACC, TSC, CP, QTI, EXC, server, task group).
Identity validation is performed by storing the PID field of the process occupying the row the first time the row is accessed. Then, when revisiting the table, get the PID along with the data values. Then check that the PID has not changed. If it has, the data refers to a new process.
Note that the process name is not a good means of identifying a process, because process names can be reused between entity executions.
Also note PID is not an ID class field for servers and task groups. For these two entity types, the EXC PID should be used.
State validation is performed by checking the collection state
for the class that contains the field. For instance, if the
exc-current-waiting-tasks-num (in the EXC run-time class) is being
monitored, ensure that the exc-rt-coll-state is enabled (equal to 1).
Otherwise, the value in that field is no longer being updated by the
EXC, and is no longer accurate.
6.4.1 Data Type Mapping
The ACMS Remote Manager implements three data types:
The integer and string data types map directly to the SNMP INTEGER and DisplayString data types.
The gauge data type defined for the Remote Manager is not the same as the SNMP Gauge type. In order to avoid confusion, the Remote Manager SNMP interface maps the Remote Manager gauge fields to SNMP INTEGER and DisplayString data types. So for each Remote Manager gauge data type, three fields are defined in the MIB: the current field value, the maximum (or minimum) field value, and the maximum (or minimum) field value time.
For example, consider the ACC run-time field current_appls. This is defined as a Remote Manager gauge data type in Section 8.2. In the MIB, three fields are defined:
acc-current-appls-num INTEGER, acc-current-appls-max INTEGER, acc-current-appls-time DisplayString |
This is the case for all Remote Manager gauge data types. For
Remote Manager min gauge data types, there is a -min field
instead of a -max field. For both gauge data types, time is
expressed in the form DD-MMM-YYYY HH:MM:SS.hh.
6.4.2 Single-Row Tables
Access to single-row tables is straightforward, because only a single row is ever accessed. The following are single-row tables:
Bounds checking need not be performed. However, for Entity tables (ACC,
QTI, TSC), both identity and state validation must be performed.
6.4.3 Static Tables
Static tables are sized when the parent process starts and do not change as long as the parent process is running. For each static table, there is a field in the table of the parent process that indicates the upper bound of the static table.
Table 6-1 shows the static tables, their parent process, and the field that indicates the upper bound of the table.
| Table | Parent Process | Upper Bound (field and table) |
|---|---|---|
| CP | TSC | tsc-cp-slots-active in the TSC table |
| EXC | ACC | acc-max-appl-active in the ACC table |
| Server | EXC | exc-server-types in the EXC table |
| Task Group | EXC | exc-task-groups in the EXC table |
| Interfaces | Remote Manager | rmIfCt in the Remote Manager table |
| Collection | Remote Manager | totl-entity-slots in the Parameter table |
In static tables, table data is not always contiguous and table rows can be reused. The PID field should be used to establish process identity.
For example, consider the following CP table. Assume that the first CP is permanent, and the second two are not.
Table Row CP process name CP PID 1 ACMS01CP001000 2040013D 2 ACMS01CP002000 2040013E 3 ACMS01CP003000 2040013F |
An SNMP console searching this table sequentially would find all three CP instances; access to table row 4 would return an error. However, if the users attached to the CP in table row 2 log out, the CP terminates and the table now looks like this:
Table Row CP process name CP PID 1 ACMS01CP001000 2040013D 2 3 ACMS01CP003000 2040013F |
An SNMP console searching this table sequentially and stopping when the first error is returned would find only the first CP. Access to the second row would return an error. Therefore, when scanning static tables, it is important to examine all rows of the table before terminating the scan; that is, perform a loop based on the tsc-cp-slots-active field in the TSC table.
Finally, consider what happens if a new CP now starts. The table would look as follows:
Table Row CP process name CP PID 1 ACMS01CP001000 2040013D 2 ACMS01CP002000 20400140 3 ACMS01CP003000 2040013F |
Table row 2 is now valid again, but a different process occupies it.
Therefore, any cached information for table row 2 is invalid and must
be refreshed with the data from the new process.
6.4.4 Dynamic Tables
Dynamic tables do not have a fixed upper bound; they grow and shrink as entries are added and removed. However, data in dynamic tables is always contiguous, so there are never invalid rows stored between valid rows. When a row becomes invalid because it is empty or unoccupied, it is removed from the table and the remaining rows are renumbered.
The following are dynamic tables:
To see how a dynamic table changes when a table row is removed, assume that a user table has the following contents:
Table row User Name Client Id 1 User1 1 2 User2 2 3 User3 3 4 User4 4 |
If User2 logs out, the contents of the table would change as follows:
Table row User Name Client Id 1 User1 1 2 User3 3 3 User4 4 |
As with static tables, you must ensure that the table row being
accessed has not been reused or renumbered. Among dynamic tables, only
the Trap table allows updates. Note that entries are never deleted or
modified in the Log table; new entries are always appended to the end.
6.4.5 Servers and Task Groups
The Servers and Task Group tables are indexed by a compound index. For both tables, the first key value is the table row of the owning EXC; the second key value is the Server or Task Group row. When fetching or setting Server or Task Group rows, you must first determine the EXC (application) they belong to, and then determine the particular server or task group.
For example, assume the EXC table has a total of four rows. Application Appl1 occupies row 1, and has two servers (ServerA and ServerB) and one task group (TaskGroupA). Application Appl2 occupies row 3 and has two servers (ServerC and ServerD) and two task groups (TaskGroupB, TaskGroupC). EXC table rows 2 and 4 are unused. Table 6-2 and Table 6-3 list the contents of each table.
| Row | Contents |
|---|---|
| 1 | Appl1 |
| 2 | (unused) |
| 3 | Appl2 |
| 4 | (unused) |
| Key 1 (EXC) | Key 2 (Server) | Contents |
|---|---|---|
| 1 | 1 | ServerA |
| 1 | 2 | ServerB |
| 3 | 1 | ServerC |
| 3 | 2 | ServerD |
| Key 1 (EXC) | Key 2 (Task Group) | Contents |
|---|---|---|
| 1 | 1 | TaskGroupA |
| 3 | 1 | TaskGroupB |
| 3 | 2 | TaskGroupC |
In order to access the ser-server-name field for ServerA in application Appl1, the OID would be 1.3.6.1.4.1.36.2.18.48.14.1.3.1.1 To access the same field for ServerD in Appl2, the OID would be 1.3.6.1.4.1.36.2.18.48.14.1.3.3.2.
There is no way to determine to which task group a server belongs. In
contrast, you can always determine from the OID which application a
server belongs to because ACMS requires that each server be given a
unique name within the application.
6.5 SNMP GET Operations
SNMP get requests are satisfied at the time they are received by the subagent. Get requests can take one of three forms: get, get next, and get bulk.
The SNMP subagent for ACMS supports only the first operation. SNMP "walks", if performed, return unpredictable results.
OIDs for ACMS Management tables are documented in Appendix C. The MIB definition for the ACMS subtree is provided in the ACMS$RM_EXAMPLES directory, in the file MGMTMIB.MY.
In order for SNMP get requests to complete successfully, the following conditions must be met:
General eSNMP return codes are returned from the Remote Manager for
SNMP get requests (see Section 6.10). For details about a specific
error, refer to the Remote Manager log.
6.6 SNMP SET Operations
SNMP set requests are executed at the time they are received by the subagent and are applied to the running system. However, not all fields that can be set are dynamic; the actual implementation of modification may not occur until the affected entities are restarted.
For more discussion about updates that modify the ACMS run-time system, see Section 4.3.
OIDs for ACMS Management tables are documented in Appendix C. The MIB definition for the ACMS subtree is provided in the ACMS$RM_EXAMPLES directory in file MGMTMIB.MY.
In order for SNMP set requests to complete successfully, the following conditions must be met:
General eSNMP return codes for SNMP get requests are returned from the
Remote Manager (see Section 6.10). For details about a specific error,
refer to the Remote Manager log.
6.7 Using SNMP to Start and Stop ACMS Entities
To start and stop ACMS entities (or to stop the Remote Manager), the Remote Manager allows SNMP users to modify the ID class field running_state. In general, ID class fields are read only. However, since SNMP does not support a START or STOP command, the SET command must be used.
Modifications to the running_state fields are not performed directly by the Remote Manager. Instead, the Remote Manager uses ACMSOPER commands to request the shutdown or startup of the ACMS entity. The ACMS entities update the running_state field when they start or stop.
For instance, to start the ACMS run-time system, an SNMP console program issues an SNMP SET command for the ACC running_state OID, specifying the value "started". The Remote Manager interprets this message as an attempt to start the system and issues the appropriate ACMSOPER command.
The SNMP set call is synchronous. That is, it does not complete until the ACMS operation has completed.
Failure messages related to start or stop requests are written to the
Remote Manager log.
6.8 SNMP Traps
SNMP traps provide a means of automatically notifying the system support team when a warning or error condition exists. Users configure SNMP traps in the SNMP trap table; when a matching condition or event occurs, an SNMP trap is generated. SNMP management consoles listen for SNMP traps and then respond in a console-dependent (and usually user-configurable) manner.
See Section 8.12 for a discussion of the Trap table and the format of trap messages.
At run time, SNMP traps can be generated as the result of either an ACMS process starting or stopping, or an event that occurred within the Remote Manager (for example, a failure in communications with ACMS).
ACMS system managers configure traps by modifying the Trap table, either by using the ACMSCFG utility prior to Remote Manager startup or by using the ACMSMGR utility after the Remote Manager has been started. Changes made using ACMSCFG do not affect the running system until the Remote Manager is restarted; changes made using ACMSMGR are not saved when the Remote Manager stops.
The configuration process is the same with either utility. You use the ADD TRAP command to add new traps, use the DELETE TRAP command to remove traps, and use the SET TRAP command to modify traps.
Keep in mind that although you can add, delete, or modify entries in the trap table at almost any time, traps will not be generated unless the SNMP interface is started. In addition, traps are not queued if the SNMP interface is disabled.
The combination of entity, name, and parameter uniquely identify a trap in the Trap table. For each trap, a minimum and a maximum value can be specified, along with a severity. Minimum and maximum trap values specify thresholds that trigger traps when the associated parameter is either greater than or less than the threshold. Minimum and maximum trap values are parameter specific.
A special value of -1 is used as a placeholder when creating a trap for which a minimum or maximum does not apply. In many situations, only the minimum or maximum value setting is meaningful. In this instance, set the desired field (minimum or maximum) to the threshold value, and set the other to -1.
Two trap parameters are supported:
The trap parameter EXISTS allows traps to be generated based on whether an ACMS process starts or stops.
Specifying a minimum trap value of 1 for a process specifies, in effect, that a trap should be generated whenever the process stops --- that is, when the process existence is less than 1.
Specifying a maximum value of 0 specifies that a trap should be generated whenever the process starts --- that is, when the processes existence is greater than 0.
A minimum value of 0 or a maximum value of 1, while valid, is basically
useless, since the EXISTS parameter is never greater than 1 or less
than 0.
6.8.2 EVENT_SEVERITY Traps
The trap parameter EVENT_SEVERITY allows traps to be generated based on the facility and severity of events being logged to the Remote Manager log. For example, an EVENT_SEVERITY trap can be configured for Remote Manager SNMP events with severity higher than WARNING (such as ERROR or FATAL). Any time a Remote Manager SNMP operation fails with a severity higher than WARNING, an SNMP trap is generated.
Other facilities that can be monitored are:
Use care when you configure traps so that you do not create unnecessary
traps. In general, traps are intended to be used to signal significant
events. For instance, specifying a minimum severity of FATAL or ERROR
causes all informational and warning messages to generate traps. This
is probably not a good use of network or console resources.
6.9 SNMP Debug Tracing
In addition to the normal logging the Remote Manager performs, it is possible to enable debug-level SNMP tracing. This level of tracing is performed by the eSNMP TCP/IP code layer and may not be available for all TCP/IP products. The Compaq TCP/IP Services for OpenVMS product supports debug-level SNMP tracing. If you use a third-party TCP/IP product, check with that vendor regarding support for this option.
Debug-level tracing of the Remote Manager SNMP interface can be valuable for developing SNMP console applications or for trying to debug a particular SNMP environmental problem. However, it is relatively resource intensive and should be performed in a controlled environment for short durations.
To enable debug-level SNMP tracing, the Remote Manager must be started with the command line argument LOG_TO_SYSOUT, as follows:
|
@sys$startup:acms$mgmt_startup LOG_TO_SYSOUT |
The SNMP_AUDIT_LEVEL parameter must be greater than 0. When the SNMP
interface is started, it will enable debug-level tracing in the eSNMP
code layer. All output is directed to SYS$OUTPUT for the Remote Manager
process, which is redirected by the startup command procedure to
SYS$ERRRORLOG:ACMS$MGMT_SERVER.OUT.
6.9.1 Starting SNMP Debug Tracing
To start the Remote Manager with debug-level SNMP tracing, run the startup command procedure SYS$STARTUP:ACMS$MGMT_STARTUP, specifying LOG_TO_SYSOUT as the only parameter to the command procedure, as follows:
$ @SYS$STARTUP:ACMS$MGMT_STARTUP LOG_TO_SYSOUT |
Once the Remote Manager has been started and the SNMP interface has been enabled, make sure that the SNMP_AUDIT_LEVEL parameter is greater than 0. To do this, use the following ACMSMGR command:
$ ACMSMGR SET PARAM/SNMP_AUDIT_LEVEL=F |
The SNMP debug output is written to SYS$ERRORLOG:ACMS$MGMT_SERVER.OUT, which is an ASCII file that can be typed or edited.
| Previous | Next | Contents | Index |