# Compaq ACMS for OpenVMS
Remote Systems Management Guide

Previous | Contents | Index

# 8.21 ACMSMGMT_LIST_INTERFACES_1

ACMS Remote Manager clients call this procedure to obtain information about all configured interfaces for a Remote Manager server on a local or remote node.

## Format

> ### interfaces_rec_out *acmsmgmt_list_interfaces_1 (sub_id_struct *sub_rec, CLIENT *cl)

## Parameters

> ### sub_rec

> Type: | Sub_id_struct
> Access: | Read |
> Mechanism: | By reference |
> Usage: | Structure that contains the following client authorization information.
> | 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.

> ### 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: | Interfaces_rec_out
> Access: | Write
> Mechanism: | By reference
> Usage: | Pointer to a record that contains a union consisting of either a failure code or a pointer to the start of a linked list of records. See the Description section for a discussion of the structure of the union. The records contain all the fields of the Interfaces table (see Section 9.7).

## Description

> The ACMSMGMT_LIST_INTERFACES_1 procedure returns an array of Remote Manager Interfaces table rows. All records in the table are returned. Each record represents a separate interface, as determined by the interface_type field.

> The return record is a union containing either a failure code or the first record in the list, as follows:

>            struct interfaces_rec_out {
>                    int status;
>                    union {
>                            interfaces_rec_out_r interfaces;
>                            int rc;
>                    } interfaces_rec_out_u;
>            };

> To determine the status of the call and the contents of the return record, first check the status field. The following are possible values in the status field:

> - MGMT_FAIL
>   The call has failed and the rc field contains a specific error code describing the failure.
> - MGMT_SUCCESS
>   The call completed successfully. All rows in the table were returned.

> The array is contained in a structure of type interfaces_rec_out_r with an integer field (num_elements) containing the size of the array, as follows:

>            struct interfaces_rec_out_r {
>                    int         num_elements;
>                    interfaces_rec   values[MGMT_K_MAX_IF];
>                    };

## Example

    int list_interfaces_data(int client_id,CLIENT *cl)
     {

       interfaces_rec_out   *if_ptr;
       interfaces_rec_out_r *inter;
       static struct sub_id_struct sub_rec;
       int status;

       sub_rec.client_id = client_id;

       if_ptr = acmsmgmt_list_interfaces_1(&sub_rec,cl);

       if (!if_ptr) {
          printf("\n RPC Call to get Interfaces data failed");
          return(MGMT_FAIL);
       }

       inter = &if_ptr->interfaces_rec_out_u.interfaces;
       if (if_ptr->status == MGMT_FAIL) {
          printf("\n Call to get Interfaces data failed, returning status code
                 %d",if_ptr->interfaces_rec_out_u.rc);
          status = if_ptr->interfaces_rec_out_u.rc;
            xdr_free(xdr_interfaces_rec_out, if_ptr);
            free(if_ptr);
          return(status);
       }

       printf("\n RPC  interface has processed %d read requests",
              inter->values[0].get_request_count);
       printf("\n SNMP interface has processed %d read requests",
              inter->values[1].get_request_count);
         xdr_free(xdr_interfaces_rec_out, if_ptr);
         free(if_ptr);
       return(0);
    }

> In the preceding example, the ACMSMGMT_LIST_INTERFACES_1 procedure is called to fetch the contents of the Interfaces table. If the call succeeds, the number of read requests by each interface is printed from the retrieved record. 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.22 ACMSMGMT_LIST_LOG_1

ACMS Remote Manager clients call this procedure to obtain information from a Remote Manager log on a local or remote node.

## Format

> ### log_data_list *acmsmgmt_list_log_1 (log_sel_struct *log_rec, CLIENT *cl)

## Parameters

> ### log_rec

> Type: | Log_sel_struct
> Access: | Read |
> Mechanism: | By reference |
> Usage: | Defines which log records to return. The log_sel_struct contains the following 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.
> | before_time
> | Type: | Null-terminated character string
> | Access: | Read, optional
> | Mechanism: | By reference
> | Usage: | Pointer to a null-terminated character string containing a valid OpenVMS ASCII time string. This field determines the chronological starting point for the list of records to be returned. If omitted, records are returned beginning at the start of the file. Format is OpenVMS ASCII time ( DD-MMM-YY HH:MM:SS.hh).
> | since_time
> | Type: | Null-terminated character string
> | Access: | Read, optional
> | Mechanism: | By reference
> | Usage: | Pointer to a null-terminated character string containing a valid OpenVMS ASCII time string. This field determines the chronological ending point for the list of records to be returned. If omitted, records are returned until end of file is reached. Format is OpenVMS ASCII time ( DD-MMM-YY HH:MM:SS.hh).
> | file_name
> | Type: | Null-terminated character string
> | Access: | Read, optional
> | Mechanism: | By reference
> | Usage: | Pointer to a null-terminated character string containing either a valid OpenVMS file specification or a logical name pointing to a valid OpenVMS file specification. This field determines the log file to be processed. An empty string requests the default (currently open) log file.
> | dup_count
> | Type: | Integer
> | Access: | Read
> | Mechanism: | By value
> | Usage: | A sequential counter of records with the same time. This allows records to be unique even if they were generated at the same time. Set this value to -1 for the initial call.
> | facility
> | Type: | Integer
> | Access: | Read, optional
> | Mechanism: | By value
> | Usage: | Value of a valid Remote Manager facility. If specified, only audit records with matching facility codes are returned. Facility codes are listed in Section 8.1.5.
> | severity
> | Type: | Integer
> | Access: | Read, optional
> | Mechanism: | By value
> | Usage: | Value of a valid Remote Manager severity. If specified, only audit records with matching severity are returned. Severities are listed in Section 8.1.7.

> ### 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: | Log_data_list
> Access: | Write
> Mechanism: | By reference
> Usage: | Pointer to a union. The union contains either a failure code or a pointer to the start of a linked list of records. See the Description section for a discussion of the structure of the union. The following are the contents of this record:
> | log_data_list
> | Type: | Logging_rec
> | Access: | Write
> | Mechanism: | By reference
> | Usage: | Pointer to a structure of type logging_rec.
> | dup_count
> | Type: | Integer
> | Access: | Write
> | Mechanism: | By value
> | Usage: | Integer value with uniquely identifies records generated at the same time.
> | log_msg
> | Type: | Null-terminated character string
> | Access: | Write
> | Mechanism: | By reference
> | Usage: | Pointer to a null-terminated character string containing the audit information.
> | pNext
> | Type: | Log_list
> | Access: | Write
> | Mechanism: | By value
> | Usage: | Pointer to the next record in the linked list.

## Description

> Note The ACMSMGMT_LIST_LOG_1 procedure is also described in detail in Section 6.6.1.

> The ACMSMGMT_LIST_LOG_1 procedure returns a linked list of Remote Manager log entries, ordered by time. The records to be returned are determined by the fields specified in the log_sel_struct input argument. Records can be selected by date and time, facility, and severity. Note that only max_rpc_return_rec data (Parameter table field) is returned in each call. The end of data is signaled by the status field (see the following example). If the end of data is not signaled, repeated calls are needed to fetch all matching records.

> The return record is a union containing either a failure code or the first record in the list:

>            struct log_data_list {
>                    int status;
>                    union {
>                            int rc;
>                            log_list list;
>                    } log_data_list_u;
>            };

> To determine the status of the call and the contents of the return record, first check the status field. The following are possible values in the status field:

> - MGMT_FAIL
>   The call has failed and the rc field contains a specific error code describing the failure.
> - MGMT_NOMORE_DATA
>   There are no more records in the file. The linked list may or may not contain the final records, depending on whether any more records matched the selection criteria.
> - MGMT_SUCCESS
>   The call completed successfully. More records exist than were returned in the call.

> The ACMSMGMT_LIST_LOG_1 procedure returns n records per call, where n is determined by the Remote Manager parameter field max_rpc_return_recs. Therefore, repeated calls may be necessary to retrieve all records that match the selection criteria. Context is not maintained by the server between calls; the selection criteria are evaluated on each call by the Remote Manager. Following the initial call, callers should place the correct time value in the since_time field of the log_sel_struct input argument, as well as the correct dup_count value in order to have the chronologically next n records returned.

> This procedure does not require the ACMS run-time system to execute.

## Example

    int list_log_data(int client_id,CLIENT *cl)
    {

       int  skip_rec          = 0;
       char null_time_str[24] = "";
       char first_of_jan[24]  = "01-JAN-1998 00:00:00.00";
       char file_spec[]       = ""; /* use default, i.e. active log file */
       char time_cache[MGMT_S_TIME_A+1];
       static struct  log_sel_struct log_rec;
       log_data_list  *log;
       log_link  *nl;
       int status;

       /* Initialize log selection data */

       log_rec.client_id   = client_id;
       log_rec.before_time = null_time_str;
       log_rec.since_time  = first_of_jan;
       log_rec.file_name   = file_spec;
       log_rec.dup_count   = -1;
       log_rec.facility    = -1; /* don't match on facility */
       log_rec.severity    = -1; /* don't match on severity */

    top:

       log = acmsmgmt_list_log_1(&log_rec,cl);

       if (!log)
          return(MGMT_FAIL);

       if (log->status == MGMT_FAIL) {
          status = log->log_data_list_u.rc;
            xdr_free(xdr_log_data_list, log);
            free(log);
          return(status);
       }

       for (nl = log->log_data_list_u.list; nl != NULL; nl = nl->pNext) {
          if (skip_rec)
             skip_rec = 0;
          else
             printf("\n %-12s\t%-s",sname,nl->log_data.log_msg);

             memcpy(&time_cache[0],nl->log_data.log_msg,23);
             log_rec.dup_count  = nl->log_data.dup_count;
             log_rec.since_time = time_cache;
       }

       if (log->status == MGMT_NOMORE_DATA)
             printf("\n *** End of data **");

       else {
             skip_rec = 1;
             goto top;
       }

         xdr_free(xdr_log_data_list, log);
         free(log);
       return(0);
    }

> In the preceding example, the ACMSMGMT_LIST_LOG_1 procedure is called to fetch the contents of the RM log file. All entries since January 1, 1998 are requested. If the call succeeds, each entry is printed out. Otherwise, an error message is displayed. This example is very similar to the one described in detail in Chapter 6. The example in Section 6.4.1 shows how to declare and initialize the input arguments to this procedure.

# 8.23 ACMSMGMT_LIST_PROC_1

ACMS Remote Manager clients call this procedure to obtain a list of ACMS processes running on a particular node, along with some collection state information for each process.

## Format

> ### proc_data_list *acmsmgmt_list_proc_1 (sub_id_struct *sub_rec, CLIENT *cl)

## Parameters

> ### sub_rec

> Type: | Sub_id_struct
> Access: | Read |
> Mechanism: | By reference |
> Usage: | Structure that contains the following client authorization information.
> | 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.

> ### 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: | Proc_data_list
> Access: | Write
> Mechanism: | By reference
> Usage: | Pointer to a record that contains a union consisting of either a failure code or a pointer to a structure of type proc_link, which contains the start of a linked list of records. The following are the contents of this union:
> | rc
> | Type: | Integer
> | Access: | Write
> | Mechanism: | By value
> | Usage: | Failure return code.
> | list
> | Type: | Proc_list
> | Access: | Write
> | Mechanism: | By reference
> | Usage: | Start of linked list. Pointer to a structure of process data, and a forward pointer to the next node in the linked list. The following are the contents of this structure:
> |  | pNext
> |  | Type: | Proc_list
> |  | Access: | Write
> |  | Mechanism: | By value
> |  | Usage: | Start of linked list. Pointer to a structure of type user_list.
> |  | proc_data
> |  | Type: | Proc_rec
> |  | Access: | Write
> |  | Mechanism: | By reference
> |  | Usage: | The data describing the process. This record contains the following fields:
> |  |  | record_state
> |  |  | Type: | Integer
> |  |  | Access: | Write
> |  |  | Mechanism: | By value
> |  |  | Usage: | The current state of the record. Will be either MGMT_VALID or MGMT_INACTIVE.
> |  |  | entity_type
> |  |  | Type: | Integer
> |  |  | Access: | Write
> |  |  | Mechanism: | By value
> |  |  | Usage: | The type of ACMS entity the process is. Entity types are listed in Section 8.1.4.
> |  |  | pid
> |  |  | Type: | Integer
> |  |  | Access: | Write
> |  |  | Mechanism: | By value
> |  |  | Usage: | OpenVMS Process ID.
> |  |  | process_name
> |  |  | Type: | Null-terminated string
> |  |  | Access: | Write
> |  |  | Mechanism: | By reference
> |  |  | Usage: | The OpenVMS process name.
> |  |  | class_states
> |  |  | Type: | Array of integers
> |  |  | Size: | 5
> |  |  | Access: | Write
> |  |  | Mechanism: | By value
> |  |  | Usage: | An array of integers. Each array element represents the collection state for a class. Positions are: 0: ID 1: CONFIG 2: RUNTIME 3: POOL 4: ERROR

## Description

> The ACMSMGMT_LIST_PROC_1 procedure returns a linked list of processes that a particular Remote Manager is aware of. The Remote Manager builds this list from the various ACMS Entity tables (Chapter 9). For each process, the Remote Manager populates a proc_data record.

> Previous | Next | Contents | Index