| Previous | Contents | Index |
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.
7.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.
7.9.2 Stopping SNMP Debug Tracing
To stop debug-level SNMP tracing, either restart the Remote Manager (without the LOG_TO_SYSOUT parameter), or use the following command to set the SNMP_AUDIT_LEVEL parameter to 0:
$ ACMSMGR SET PARAM/SNMP_AUDIT_LEVEL=0 |
Table 7-5 describes the return codes returned by the Remote Manager eSNMP routines.
| Return Code | Description |
|---|---|
| ESNMP_MTHD_commitFailed | An attempt to apply an update failed. This is also returned from a start or stop attempt that fails. Refer to the Remote Manager log for details. |
| ESNMP_MTHD_genErr | An internal error occurred. This could be due to security violations, a failure updating a particular field, or an internal processing error. Refer to the Remote Manager log for details. |
| ESNMP_MTHD_noCreation | The table does not allow new rows to be created. The OID specified for the set operation indicates a table row that does not exist, and the table does not allow new rows to be created. |
| ESNMP_MTHD_noError | The set operation was successful. |
| ESNMP_MTHD_noSuchInstance | A request was made for a variable that does not exist. Either the OID is invalid, or the particular table row does not exist (is out of bounds). |
| ESNMP_MTHD_noSuchObject | The column specified does not exist. |
| ESNMP_MTHD_notWritable | An attempt was made to set a variable that is read only. |
| ESNMP_MTHD_resourceUnavailable | The table row exists (is within the bounds of the table) but is currently unused (empty). |
| ESNMP_MTHD_wrongValue | An attempt was made to update a field with an invalid value. |
The Management APIs are intended to be called from Open Network Computing (ONC) Remote Procedure Call (RPC) clients. ONC RPC Interface Definition Language (IDL) for all procedures is contained in the file ACMS$RM_EXAMPLES:ACMSMGMT_RPC.X.
Programmers who write client programs are strongly urged to become familiar with the contents of this file. Many programming questions can be answered by looking at the actual RPC definitions. All structure definitions, for example, are contained within this file.
The procedures documented in this chapter are based on the most current record and field data available with Version 4.4 of the Remote Manager. Procedures names with _2 indicate new or modified API functions that take advantage of this new data. These procedures should only be called from a Remote Manager Version 4.4 server system.
To ensure backwards compatibility, the _1 version of all calls is still available and provided with the Remote Manager Version 4.4 software.
The acms$mgmt_get_creds procedure is not included in the ACMSMGMT_RPC.X IDL because it is not a remote procedure call. It is a statically linked, locally executed function for those clients performing explicit authentication. The ACMS$MGMT_GET_CREDENTIALS.OBJ object module is located in the ACMS$RM_EXAMPLES directory. The acms$mgmt_get_creds procedure is for use by ONC RPC clients only. |
The tables in this section list commonly used fields and their values.
8.1.1 Collection Classes
Table 8-1 shows the symbolic names for Remote Manager collection classes.
| Symbolic Name | Description |
|---|---|
| MGMT_CLASS_ALL | All classes |
| MGMT_CLASS_CFG | Config class |
| MGMT_CLASS_ERROR | Error class |
| MGMT_CLASS_ID | ID class |
| MGMT_CLASS_POOL | Pool class |
| MGMT_CLASS_RT | Runtime class |
Table 8-2 shows the symbolic names for Remote Manager interfaces.
| Symbolic Name | Description |
|---|---|
| MGMT_IF_RPC | Remote Procedure Call (RPC) interface |
| MGMT_IF_SNMP | Simple Network Management Protocol (SNMP) interface |
Table 8-3 shows the symbolic names for Remote Manager enable states.
| Symbolic Name | Description |
|---|---|
| MGMT_STATE_DISABLED | Disabled |
| MGMT_STATE_ENABLED | Enabled |
Table 8-4 shows the symbolic names for Remote Manager entity types.
| Symbolic Name | Description |
|---|---|
| MGMT_ACC | Application Central Controller (ACC) process |
| MGMT_ALL | All entities |
| MGMT_CP | Command Process (CP) process |
| MGMT_EXC | Application Execution Controller (EXC) process |
| MGMT_MGR | Remote Manager process |
| MGMT_QTI | Queued Task Initiator (QTI) process |
| MGMT_SER | Procedure server types |
| MGMT_TG | Task groups |
| MGMT_TSC | Terminal Subsystem Controller (TSC) process |
| MGMT_UNSUPPORTED | Null value |
Table 8-5 shows the symbolic names for Remote Manager facility types.
| Symbolic Name | Description |
|---|---|
| MGMT_FAC_ALL | Any facility type. |
| MGMT_FAC_DCL | A thread that manages a spawned DCL process. The DCL process is used to execute ACMSOPER commands. |
| MGMT_FAC_LOG | The event log writer thread. |
| MGMT_FAC_MGR | The mainline Remote Manager process. |
| MGMT_FAC_MSGPROC | A thread that handles messages coming in from ACMS processes. |
| MGMT_FAC_PROCMON | A thread dedicated to monitoring processes. |
| MGMT_FAC_RPC | The RPC interface thread (listener and procedures). |
| MGMT_FAC_SEC | Security routines in the Remote Manager. |
| MGMT_FAC_SNAP | A thread dedicated to performing data snapshots. |
| MGMT_FAC_SNMP | The SNMP interface thread (message loop and procedures). |
| MGMT_FAC_TIMER | A thread that controls timers for the Remote Manager. |
| MGMT_FAC_TRAP | A thread that sends out SNMP traps. |
Table 8-6 shows the symbolic names for Remote Manager running states.
| Symbolic Name | Description |
|---|---|
| MGMT_STATE_INITED | Process or object has initialized. |
| MGMT_STATE_INITING | Process or object is initializing. |
| MGMT_STATE_LOAD_DONE | Process or object has finished loading. |
| MGMT_STATE_LOADING | Process or object is loading itself. |
| MGMT_STATE_STARTED | Process or object has started and is ready to run. |
| MGMT_STATE_STARTING | Process or object is starting the mainline. |
| MGMT_STATE_STOPPED | Process or object is stopped. |
Table 8-7 shows the symbolic names for Remote Manager severities.
Severities are generally reported as simple severities (informational, warning, error, fatal) but may be combined by logically ORing the values when used as selection criteria (such as for selecting log records).
| Symbolic Name | Description |
|---|---|
| MGMT_SEV_ERR | Error |
| MGMT_SEV_FATAL | Fatal |
| MGMT_SEV_INFO | Informational |
| MGMT_SEV_NONE | Null value |
| MGMT_SEV_WARN | Warning |
Table 8-8 shows the symbolic names for Remote Manager trap parameters.
| Symbolic Name | Description |
|---|---|
| MGMT_EXISTS | Existence traps |
| MGMT_SEVERITY | Remote Manager severity traps |
Each of the procedures documented in this chapter (and those in ACMS$MGMT_EXAMPLES.C) are designed to use the thread-safe client stub provided with the Remote Manager, as described in the file ACMS$MGMT_EXAMPLES_BUILD.COM. As a result, each procedure contains one or more "free" calls that prevent memory leaks in multithreaded client implementations.
If you intend to build a multithreaded client, you must modify any existing, customized API functions to include these calls, then recompile them along with the thread-safe client stub.
If you want to implement a non-thread safe client using the RPC-generated stub, omit the "free" calls. See ACMS$MGMT_EXAMPLES_BUILD.COM for detailed build instructions.
8.3 ACMSMGMT_ADD_COLLECTION_2
This procedure adds entries to the Remote Manager Collection table.
Collection table entries can also be modified (see Section 8.33) and
deleted (see Section 8.6).
coll_status_rec_2 *acmsmgmt_add_collection_2(coll_config_rec_2 *set_struct,CLIENT *cl)
set_struct
Type: Coll_config_rec_2 Access: Read Mechanism: By reference Usage: Structure that contains the following client identification and Collection table fields. client_id Type: Integer Access: Read Mechanism: By value Usage: If explicit authentication is being used, a valid client ID must be provided. If the value for client_id is 0, proxy access is used. Client_id is obtained by calling the acms$mgmt_get_creds procedure. coll Type: Coll_update_rec_r_2 Access: Read Mechanism: By value Usage: Structure containing a Collection table record. Collection table fields are described in Section 9.3. See the Description section for information on how to initialize this record. cl
Type: CLIENT * Access: Read Mechanism: By value Usage: Pointer to an RPC client handle previously obtained by calling the RPC routine CLNT_CREATE.
Type: Coll_status_rec_2 Access: write Mechanism: By reference Usage: Pointer to a record that contains a union consisting of either a failure code or a structure of type coll_update_rec_r_2, which contains status codes for each field. See the Description section for a discussion of how to determine the update status for any field. The following are the contents of this union: status Type: Integer Access: write Mechanism: By value Usage: Failure return code. data_warn Type: Coll_output_rec_r_2 Access: write Mechanism: By value Usage: Structure containing a Collection table record. The entries in this field contain status codes corresponding to the fields in the coll structure. See the Description section for a discussion of how to determine the update status for any field.
This procedure adds a row to the Collection table (see Section 9.3).Additions to this table are not durable; that is, they do not survive a restart of the Remote Manager. To make nondynamic, permanent updates to the Collection table, use the ACMSCFG utility.
Calls to this procedure must specify entity_type, entity_name, and collection_class. The combination of these fields must be unique within the collection table for the row to be added. Table 8-4 and Table 8-1 contain symbolic values used to populate the entity_type and collection_class fields; entity_name is specified as a null-terminated string.
ID and Config class rows cannot be added. By default, these classes are always enabled for all ACMS processes.
The Collection table contains a fixed number of rows, which is determined by the Remote Manager parameter total_entity_slots. This is a nondynamic parameter and requires a restart of the ACMS system in order to be changed. The default is 20 rows.
Additions to the Collection table are processed immediately, and may affect more than one ACMS process. See Section 5.1 for a discussion of how the Collection table affects ACMS data collection.
int add_collection_data(int client_id,CLIENT *cl)
{
static char c_name_all[] = "*";
static coll_config_rec_2 set_struct;
struct coll_status_rec_2 *status_rec;
set_struct.client_id = client_id;
set_struct.coll.entity_type = MGMT_ALL;
set_struct.coll.entity_name = c_name_all;
set_struct.coll.collection_class = MGMT_CLASS_RT;
set_struct.coll.collection_state = MGMT_STATE_DISABLED;
status_rec = acmsmgmt_add_collection_2(&set_struct,cl);
if (!status_rec) {
printf("\n Call to add collection failed");
return(MGMT_FAIL);
}
if (status_rec->status == MGMT_WARN) {
printf("\nThe following updates failed: ");
if (status_rec->coll_status_rec_2_u.data_warn.entity_type == MGMT_FAIL)
printf("\n entity type invalid");
if (status_rec->coll_status_rec_2_u.data_warn.collection_state
== MGMT_FAIL)
printf("\n coll_state invalid");
if (status_rec->coll_status_rec_2_u.data_warn.storage_state == MGMT_FAIL)
printf("\n storage_state invalid");
if (status_rec->coll_status_rec_2_u.data_warn.storage_interval
== MGMT_FAIL)
printf("\n storage_interval invalid");
}
else if (status_rec->status != MGMT_SUCCESS) {
printf("\nCall to add collection with status %d",
status_rec->coll_status_rec_2_u.rc);
xdr_free(xdr_coll_status_rec_2, status_rec);
free(status_rec);
return(MGMT_FAIL);
}
else
printf("\nCall to add collection was executed");
xdr_free(xdr_coll_status_rec_2, status_rec);
free(status_rec);
return(0);
}
|
In the preceding example, the ACMSMGMT_ADD_COLLECTION_2 procedure is called to add a row to the Collection table. The row added is for entity type of * (all), entity name of * (all), and collection class RUNTIME. The collection state is set to DISABLED. If the call succeeds, a Collection table row is added, and the RUNTIME collection state for some processes may be disabled. Otherwise, an error message is displayed. The example in Section 6.4.1 shows how to declare and initialize the input arguments to this procedure.
| Previous | Next | Contents | Index |