# Compaq ACMS for OpenVMS
Remote Systems Management Guide

Previous | Contents | Index

# 8.19 ACMSMGMT_LIST_ERR_2

ACMS Remote Manager clients call this procedure to obtain a list of the error log entries.

## Format

> ### err_data_list *acmsmgmt_list_err_2(err_sel_struct *err_sel, 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. Client_id is obtained by calling the acms$mgmt_get_creds procedure.
> | 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 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 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 error information.
> | pNext
> | Type: | Log_list
> | Access: | Write
> | Mechanism: | By value
> | Usage: | Pointer to the next record in the linked list.

## Description

> The ACMSMGMT_LIST_ERR_2 procedure returns a linked list of error 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_ERR_2 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_err_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[]       = "acms$mgmt_err_log";
       char time_cache[MGMT_S_TIME_A+1];
       struct log_sel_struct log_rec;
       log_data_list         *log;
       log_link              *nl;
       int status;

       /*  Initialize err 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;
       log_rec.severity = -1;

      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; n1 = n1->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_ERR_2 procedure is called to fetch the contents of the error log. If the call succeeds, the node, symbolic name, and code equivalent are displayed for each ACMS run-time error relayed to the Remote Manager. 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.20 ACMSMGMT_LIST_EXC_2

ACMS Remote Manager clients call this procedure to obtain a list of Application Execution Controller (EXC) (ACMS application) table entries.

## Format

> ### exc_data_list_2 *acmsmgmt_list_exc_2(exc_sel_struct *sub_rec, CLIENT *cl)

## Parameters

> ### sub_rec

> Type: | Exc_sel_struct
> Access: | Read |
> Mechanism: | By reference |
> Usage: | Structure that contains client information and application selection critera. The structure 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. Client_id is obtained by calling the acms$mgmt_get_creds procedure.
> | appl_name
> | Type: | Null-terminated string
> | Access: | Read
> | Mechanism: | By reference
> | Usage: | A pointer to an application name. The name may contain wildcard characters (*, !). Specify in all uppercase characters.

> ### 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: | Exc_data_list_2
> 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 exc_data_list_2, 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: | Exc_list_2
> | Access: | Write
> | Mechanism: | By reference
> | Usage: | Start of linked list. Pointer to a structure containing an EXC table record, and a forward pointer to the next node in the linked list. The following are the contents of this structure:
> |  | pNext
> |  | Type: | Exc_list_2
> |  | Access: | Write
> |  | Mechanism: | By value
> |  | Usage: | Start of linked list. Pointer to a structure of type coll_list.
> |  | exc_data
> |  | Type: | Exc_rec_r_2
> |  | Access: | Write
> |  | Mechanism: | By reference
> |  | Usage: | EXC table row. EXC table fields are described in Section 9.6.

## Description

> The ACMSMGMT_LIST_EXC_2 procedure returns a linked list of EXC table rows. All EXC table rows whose application_name field matches the appl_name field in the selection record are returned in each call.

> Entire table rows are returned. See Section 9.6 for a description of the fields in the exc_rec_r structure.

> If the ACMS run-time system is not running when this call is issued, the Remote Manager returns the MGMT_NOT_MAPPED error code.

> Rows in the EXC table are subject to reuse. Rows are assigned round-robin, and are not cleared until they have been reassigned. Therefore, some rows may contain data for inactive EXCs. It is the caller's responsibility to examine the record_state field to determine whether this row belongs to an active (record_state field is MGMT_VALID) or inactive (record_state field is MGMT_INACTIVE) EXC, and to process the row accordingly.

## Example

    int list_exc_data(int client_id,CLIENT *cl)
    {

       static char c_all_appls[2] = "*";
       exc_data_list_2   *exc_data;
       exc_link_2      *nl;
       static struct exc_sel_struct sub_rec;
       int status;

       sub_rec.client_id = client_id;
       sub_rec.appl_name = c_all_appls;

       exc_data = acmsmgmt_list_exc_2(&sub_rec,cl);

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

       if (exc_data->status == MGMT_FAIL)  {
          if (exc_data->exc_data_list_2_u.rc == MGMT_NOMORE_DATA) {
             printf("\n No EXC data found");
               xdr_free(xdr_exc_data_list_2, exc_data);
               free(exc_data);
             return(MGMT_FAIL);
          }
          printf("\n Call to get EXC data failed, returning status code %d",
                 exc_data->exc_data_list_2_u.rc);
          status = exc_data->exc_data_list_2_u.rc;
            xdr_free(xdr_exc_data_list_2, exc_data);
            free(exc_data);
          return(status);
       }

       if (exc_data->status == MGMT_WARN)
          printf("\n ** Warning, some data may be from inactive processes **");

       for (nl = exc_data->exc_data_list_2_u.list; nl != NULL; nl = nl->pNext) {
           if (nl->exc_data.record_state == MGMT_INACTIVE)
              printf("\n INACTIVE ");
           else
              printf("\n          ");
           printf(" PID: %8X  Application : %-s",
                   nl->exc_data.pid,
                   nl->exc_data.appl_name);
       }

       printf("\n End of data");
         xdr_free(xdr_exc_data_list_2, exc_data);
         free(exc_data);
       return(0);
    }

> In the preceding example, the ACMSMGMT_LIST_EXC_2 procedure is called to fetch the contents of the EXC table. If the call succeeds, the state of the EXC (if inactive), its PID, and its application name are displayed for each table row returned. 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