Compaq ACMS for OpenVMS
Remote Systems Management Guide

Previous Contents Index

7.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.

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:


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:


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:


7.10 Remote Manager eSNMP Return Codes

Table 7-5 describes the return codes returned by the Remote Manager eSNMP routines.

Table 7-5 Remote Manager eSNMP Routines Return Codes
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.

Part 2
Reference Information

Part 2 contains reference information for the ACMS Remote Manager.

Chapter 8
Management APIs

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.

8.1 Common RPC Fields

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.

Table 8-1 Collection Classes
Symbolic Name Description
MGMT_CLASS_ALL All classes
MGMT_CLASS_CFG Config class
MGMT_CLASS_RT Runtime class

8.1.2 Interface Types

Table 8-2 shows the symbolic names for Remote Manager interfaces.

Table 8-2 Interface Types
Symbolic Name Description
MGMT_IF_RPC Remote Procedure Call (RPC) interface
MGMT_IF_SNMP Simple Network Management Protocol (SNMP) interface

8.1.3 Enable States

Table 8-3 shows the symbolic names for Remote Manager enable states.

Table 8-3 Enable States
Symbolic Name Description

8.1.4 Entity Types

Table 8-4 shows the symbolic names for Remote Manager entity types.

Table 8-4 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

8.1.5 Facility Types

Table 8-5 shows the symbolic names for Remote Manager facility types.

Table 8-5 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.

8.1.6 Running States

Table 8-6 shows the symbolic names for Remote Manager running states.

Table 8-6 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.

8.1.7 Severity Codes

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).

Table 8-7 Severity Codes
Symbolic Name Description
MGMT_SEV_INFO Informational
MGMT_SEV_NONE Null value

8.1.8 Trap Parameters

Table 8-8 shows the symbolic names for Remote Manager trap parameters.

Table 8-8 Trap Parameters
Symbolic Name Description
MGMT_EXISTS Existence traps
MGMT_SEVERITY Remote Manager severity traps

8.2 Thread-Safe and Non-Thread Safe Clients

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.


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)



Type: Coll_config_rec_2
Access: Read  
Mechanism: By reference  
Usage: Structure that contains the following client identification and Collection table fields.
  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.
  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.


Type: CLIENT *
Access: Read  
Mechanism: By value  
Usage: Pointer to an RPC client handle previously obtained by calling the RPC routine CLNT_CREATE.

Return Value

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:
  Type: Integer
  Access: write
  Mechanism: By value
  Usage: Failure return code.
  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"); 
   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", 
        xdr_free(xdr_coll_status_rec_2, status_rec); 
      printf("\nCall to add collection was executed"); 
        xdr_free(xdr_coll_status_rec_2, status_rec); 

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