Compaq ACMS for OpenVMS
Remote Systems Management Guide


Previous Contents Index

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

6.10 Remote Manager eSNMP Return Codes

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

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

Note

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.

7.1 Common RPC Fields

The tables in this section list commonly used fields and their values.

7.1.1 Collection Classes

Table 7-1 shows the symbolic names for Remote Manager collection classes.

Table 7-1 Collection Classes
Symbolic Name Description
MGMT_CLASS_ALL All classes
MGMT_CLASS_CFG Config class
MGMT_CLASS_ID ID class
MGMT_CLASS_POOL Pool class
MGMT_CLASS_RT Runtime class

7.1.2 Interface Types

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

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

7.1.3 Enable States

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

Table 7-3 Enable States
Symbolic Name Description
MGMT_STATE_DISABLED Disabled
MGMT_STATE_ENABLED Enabled

7.1.4 Entity Types

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

Table 7-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
MGMT_UNSUPPORTED Null value

7.1.5 Facility Types

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

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

7.1.6 Running States

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

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

7.1.7 Severity Codes

Table 7-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 7-7 Severity Codes
Symbolic Name Description
MGMT_SEV_ERR Error
MGMT_SEV_FATAL Fatal
MGMT_SEV_INFO Informational
MGMT_SEV_NONE Null value
MGMT_SEV_WARN Warning

7.1.8 Trap Parameters

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

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

7.2 ACMSMGMT_ADD_COLLECTION_1

This procedure adds entries to the Remote Manager Collection table. Collection table entries can also be modified (see Section 7.25) and deleted (see Section 7.4).

Format

coll_status_rec *acmsmgmt_add_collection_1(coll_config_rec *coll_cfg_rec,CLIENT *cl)


Parameters

coll_cfg_rec

Type: Coll_config_rec
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: Struct coll_update_rec_r
  Access: Read
  Mechanism: By value
  Usage: Structure containing a Collection table record. Collection table fields are described in Section 8.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.

Return Value

Type: Struct coll_status_rec
Access: write  
Mechanism: By reference  
Usage: Pointer to a union. The union contains either a failure code or a structure of type coll_update_rec_r, 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_update_rec_r
  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.

Description

This procedure adds a row to the Collection table (see Section 8.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 7-4 and Table 7-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. They can be disabled using the ACMSMGMT_SET_COLLECTION_1 procedure.

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 4.1 for a discussion of how the Collection table affects ACMS data collection.


Example


int add_collection_data(int client_id,CLIENT *cl) 
 { 
 
   static char c_name_all[] = "*"; 
   static coll_config_rec set_struct; 
   static struct coll_status_rec *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_1(&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_u.data_warn.entity_type  == MGMT_FAIL) 
         printf("\n     entity type invalid"); 
      if (status_rec->coll_status_rec_u.data_warn.collection_state == 
MGMT_FAIL) 
         printf("\n     coll_state invalid"); 
     } 
   else if (status_rec->status != MGMT_SUCCESS) { 
      printf("\nCall to add collection failed with status 
%d",status_rec->coll_status_rec_u.rc); 
      return(MGMT_FAIL); 
   } 
   else 
      printf("\nCall to add collection was executed"); 
 
   return(0); 
} 
      

In the preceding example, the acmsmgmt_add_collection_1 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 5.3.1 shows how to declare and initialize the input arguments to this procedure.

7.3 ACMSMGMT_ADD_TRAP_1

This procedure adds entries to the Remote Manager Trap table. Trap table entries can also be modified (see Section 7.31) and deleted (see Section 7.5).

Format

trap_status_rec *acmsmgmt_add_trap_1(trap_config_rec *trap_cfg_rec,CLIENT *cl)


Parameters

trap_cfg_rec

Type: Trap_config_rec
Access: Read  
Mechanism: By reference  
Usage: Structure that contains the following client identification and Trap 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 of client_id is 0, proxy access is used. Client_id is obtained by calling the acms$mgmt_get_creds procedure.
     
  trap_entry
  Type: Struct trap_update_rec_r
  Access: Read
  Mechanism: By value
  Usage: Structure containing a Trap table record. Trap table fields are described in Section 8.12. 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.

Return Value

Type: Struct trap_status_rec
Access: Write  
Mechanism: By reference  
Usage: Pointer to a union. The union contains either a failure code or a structure of type trap_update_rec_r, 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: Trap_update_rec_r
  Access: Write
  Mechanism: By value
  Usage: Structure containing a Trap table record. The entries in this field contain status codes corresponding to the fields in the trap_entry structure. See the Description section for a discussion of how to determine the update status for any field.

Description

This procedure adds a row to the Trap table (see Section 8.12).

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 Trap table, use the ACMSCFG utility.


Previous Next Contents Index