# Compaq ACMS for OpenVMS
Remote Systems Management Guide

Previous | Contents | Index

Attempting to update an active field that is nondynamic is essentially useless, since the active field value does not change. For instance, calling this procedure with the active_sw field set to 1 and the qti_username field populated produces no change to the system.

Setting the current_sw field to 1 causes updates to be written to the current ACMSGEN file. These updates are durable (that is, they survive a restart of the ACMS sytem) but do not affect the active system until the system is restarted.

For any nonnegative integer fields, the completion status of the update is returned in the corresponding field in the return structure. For string fields, the string field value is returned, regardless of the status of the call.

In order to have one of the string fields set to a null string (that is, ""), populate the field with value "NULL". To have one of the string fields ignored, pass in a null string.

## Example

    int set_qti_data(int client_id,CLIENT *cl)
     {

       static char c_name_all[2] = "*";
       static char c_null_str[2] = "";
       static qti_config_rec_2 set_struct;
       qti_status_rec_2        *ret_struct;
       dcl_link                *nl;

       memset(&set_struct,-1,sizeof(set_struct));
       set_struct.client_id      = client_id;
       set_struct.active_sw      = 1;
       set_struct.current_sw     = 0;
       set_struct.polling_timer  = 4999;

       /* Have to provide a pointer for string conversions by XDR
          or it will qtiess vio. RM will ignore any fields with
          strlen of 0 */
       set_struct.qti_username = c_null_str;

       ret_struct = acmsmgmt_set_qti_2(&set_struct,cl);

       if (!ret_struct) {
          printf("\n Call to modify qti failed");
          return(MGMT_FAIL);
       }

       if (ret_struct->status != MGMT_SUCCESS)
          printf("\n Call to modify QTI returned the following warnings or
                 errors\n");
       else
          printf("\n Call to modify QTI completed\n");

       for (nl = ret_struct->qti_status_rec_2_u.data.cmd_output; nl != NULL;
            nl = nl->pNext)
          printf("\n %s",nl->dcl_msg);
            xdr_free(xdr_qti_status_rec_2, ret_struct);
            free(ret_struct);
          return(0);
    }

> In the preceding example, the ACMSMGMT_SET_QTI_2 procedure is called to set the ACMSGEN parameter qti_polling_timer to 4999 milliseconds. If the call succeeds, only the active value is modified, the stored value is unchanged, and a success message is displayed. 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.

# 8.39 ACMSMGMT_SET_SERVER_1

This procedure modifies server (ACMS procedure server) Config class attributes.

## Format

> ### ser_status_rec *acmsmgmt_set_server_1(ser_config_rec *set_struct,CLIENT *cl)

## Parameters

> ### set_struct

> Type: | Ser_config_rec
> Access: | Read |
> Mechanism: | By reference |
> Usage: | Structure that contains the following client identification and Server 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.
> | appl_name
> | Type: | Null-terminated string
> | Access: | Read
> | Mechanism: | By reference
> | Usage: | Name of the application to which the server to be updated belongs.
> | server_name
> | Type: | Null-terminated string
> | Access: | Read
> | Mechanism: | By reference
> | Usage: | Name of the server to update.
> | creation_delay, creation_interval, deletion_delay, deletion_interval, server_proc_dmpflag, minimum_instances, maximum_instances
> | Type: | Integer
> | Access: | Read
> | Mechanism: | By value
> | Usage: | Values to be updated. These fields correspond to the active fields of the same names in the Server table (for example, creation_delay updates the creation_delay_active field). See Section 9.11 for a discussion of these fields. All fields in this record can be updated dynamically.

> ### 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: | Ser_status_rec
> 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 ser_config_rec_out, which contains status codes for each field, as well as a linked list of status messages associated with the update. 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:
> | rc
> | Type: | Integer
> | Access: | Write
> | Mechanism: | By value
> | Usage: | Failure return code.
> | data, data_warn
> | Type: | Ser_config_rec_out
> | Access: | Write
> | Mechanism: | By value
> | Usage: | Structure containing fields corresponding to the fields in the ser_config_rec structure, as well as a linked list of status messages associated with the update. See the Description section for a discussion of how to determine the update status for any field. The following are the contents of this structure:
> |  | creation_delay, creation_interval, deletion_delay, deletion_interval, server_proc_dmpflag, minimum_instances, maximum_instances
> |  | Type: | Integer
> |  | Access: | Write
> |  | Mechanism: | By value
> |  | Usage: | Status fields corresponding to the fields in the input argument.
> |  | cmd_output
> |  | Type: | Dcl_list
> |  | Access: | Write
> |  | Mechanism: | By reference
> |  | Usage: | Pointer to a linked list of records containing status messages related to the failure of any updates. This structure contains the following fields:
> |  |  | dcl_msg
> |  |  | Type: | Null-terminated string
> |  |  | Access: | Write
> |  |  | Mechanism: | By reference
> |  |  | Usage: | The status message.
> |  |  | pNext
> |  |  | Type: | Dcl_list
> |  |  | Access: | Write
> |  |  | Mechanism: | By reference
> |  |  | Usage: | Pointer to the next node in the linked list.

## Description

> This procedure requests updates to ACMS server Config class fields contained in the Server table (see Section 9.11). Note that the Server table contains only active values.

> For any nonnegative integer fields, the completion status of the update is returned in the corresponding field in the return structure.

## Example

    int set_ser_data(int client_id,CLIENT *cl)
     {

       static char c_name_all[2] = "*";
       static char vr_appl[] = "VR_APPL";
       static ser_config_rec set_struct;
       ser_status_rec        *ret_struct;
       dcl_link              *nl;

       memset(&set_struct,-1,sizeof(set_struct));
       set_struct.client_id      = client_id;
       set_struct.appl_name      = vr_appl;
       set_struct.server_name    = c_name_all;
       set_struct.creation_delay = 20;

       ret_struct = acmsmgmt_set_server_1(&set_struct,cl);

       if (!ret_struct) {
          printf("\n Call to modify Server failed");
          return(MGMT_FAIL);
       }

       if (ret_struct->status != MGMT_SUCCESS)
          printf("\n Call to modify Server returned the following warnings or
                 errors\n");
       else
          printf("\n Call to modify Server completed\n");

       for (nl = ret_struct->ser_status_rec_u.data.cmd_output; nl != NULL;
            nl = nl->pNext)
          printf("\n %s",nl->dcl_msg);
            xdr_free(xdr_ser_status_rec, ret_struct);
            free(ret_struct);
          return(0);
    }

> In the preceding example, the ACMSMGMT_SET_SERVER_1 procedure is called to set the creation_delay parameter field for all servers in application VR_APPL to 20 seconds. If the call succeeds, this parameter field is modified for all servers in the VR_APPL, and a success message is displayed. 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.

# 8.40 ACMSMGMT_SET_TRAP_1

This procedure modifies entries in the Remote Manager Trap table. Trap table entries can also be added (see Section 8.5) and deleted (see Section 8.8).

## Format

> ### trap_status_rec *acmsmgmt_set_trap_1(trap_config_rec *set_struct,CLIENT *cl)

## Parameters

> ### set_struct

> 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: | Trap_update_rec_r
> | Access: | Read
> | Mechanism: | By value
> | Usage: | Structure containing a Trap table record. Trap table fields are described in Section 9.13. 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: | Trap_status_rec
> 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 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:
> | rc
> | 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 requests updates to fields in the Trap table (see Section 9.13).

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

> Calls to this procedure must specify entity_type, entity_name, and param_to_trap. These fields must exactly match an existing record in the Trap table for the update to be applied. Table 8-1 and Table 8-4 contain symbolic values used to populate the collection_class and entity_type fields; symbolic values to the param_to_trap field are described in Table 8-8.

> Setting fields trap_min, trap_max, or severity to -2 excludes them from being updating. Otherwise, the corresponding field in the matching trap record is modified. (-1 is a special value that causes the field to be ignored when evaluating the trap conditions; see Section 7.8.)

> Updates to the Trap table are processed immediately and may affect more than one ACMS process. See Section 7.8 for a discussion of how to set SNMP traps.

## Example

    int set_trap_data(int client_id,CLIENT *cl)
     {

       static char c_name_all[2] = "*";
       static trap_config_rec set_struct;
       struct trap_status_rec *status_rec;

       set_struct.client_id                  = client_id
       set_struct.trap_entry.entity_type     = MGMT_ACC;
       set_struct.trap_entry.entity_name     = c_name_all;
       set_struct.trap_entry.param_to_trap   = MGMT_EXISTS;
       set_struct.trap_entry.min             = 1;
       set_struct.trap_entry.max             = -1;
       set_struct.trap_entry.severity        = MGMT_SEV_FATAL;

       status_rec = acmsmgmt_set_trap_1(&set_struct,cl);

       if (!status_rec) {
          printf("\n Call to modify trap failed");
          return(MGMT_FAIL);
       }

       if (status_rec->status == MGMT_WARN) {
          printf("\nThe following updates failed: ");
          if (status_rec->trap_status_rec_u.data_warn.entity_type  == MGMT_FAIL)
              printf("\n     entity_type not found or invalid");
          if (status_rec->trap_status_rec_u.data_warn.param_to_trap == MGMT_FAIL)
              printf("\n     param not found or invalid");
          if (status_rec->trap_status_rec_u.data_warn.min   == MGMT_FAIL)
              printf("\n     min invalid");
          if (status_rec->trap_status_rec_u.data_warn.max   == MGMT_FAIL)
              printf("\n     max invalid");
          if (status_rec->trap_status_rec_u.data_warn.severity  == MGMT_FAIL)
              printf("\n     severity invalid");
         }

       else if (status_rec->status != MGMT_SUCCESS) {
          printf("\nCall to modify trap failed with status %d",
                 status_rec->trap_status_rec_u.rc);
            xdr_free(xdr_trap_status_rec, status_rec);
            free(status_rec);
          return(MGMT_FAIL);
       }
       else
          printf("\nCall to modify trap was executed");
            xdr_free(xdr_trap_status_rec, status_rec);
            free(status_rec);
        return(0);
    }

> In the preceding example, the ACMSMGMT_SET_TRAP_1 procedure is called to set the trap_min field to 1, the trap_max field to -1, and the trap severity to FATAL for a trap based on an entity_type of ACC, an entity_name of * (all), and a trap parameter of EXISTS. The effect of this change is to cause a fatal-level trap to be generated if the ACC on the target node is stopped. If the call succeeds, the trap is reconfigured in the Trap table in memory. 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