# Compaq ACMS for OpenVMS
Remote Systems Management Guide

Previous | Contents | Index

# 8.16 ACMSMGMT_GET_VERSION_2

ACMS Remote Manager clients call this procedure to obtain version information for ACMS.

## Format

> ### version_data_list_2 *acmsmgmt_get_version_2(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: | version_data_list_2
> Access: | Write
> Mechanism: | By reference
> Usage: | Pointer to record returned. If NULL, the RPC has failed. If not null, the record contains either an error code in the status field (the RPC succeeded, but the call failed for another reason) or the data requested.

## Description

> The return pointer points to a record of type version_data_list_2, which constains a union consisting of either a failure return code or a pointer to a version record.

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

## Example

    int get_version_data(int client_id,CLIENT *cl2)
     {

       struct sub_id_struct sub_rec;
       version_data_list_2  *version;
       int status;

       sub_rec.client_id = client_id;

       version = acmsmgmt_get_version_2(&sub_rec,cl2);

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

       if (version->status != MGMT_SUCCESS) {
          printf("\n Call to get Version data failed, returning status code %d",
                 version->status);
          status = version->status;
            xdr_free(xdr_version_data_list_2, version);
            free(version);
          return(status);
       }

       printf("\n ACMS version is %s",version->
              version_data_list_2_u.data.acms_version);
         xdr_free(xdr_version_data_list_2, version);
         free(version);
       return(0);
    }

> In the preceding example, the ACMSMGMT_GET_VERSION_2 procedure is called to fetch ACMS version information. If the call succeeds, the version of the installed ACMS software 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.17 ACMSMGMT_LIST_COLLECTIONS_2

ACMS Remote Manager clients call this procedure to obtain a list of Collection table entries.

## Format

> ### coll_data_list_2 *acmsmgmt_list_collections_2(coll_sel_struct *coll_rec, CLIENT *cl)

## Parameters

> ### coll_rec

> Type: | Coll_sel_struct
> Access: | Read |
> Mechanism: | By reference |
> Usage: | Defines starting point for list of records to be returned. Also identifies the user. The coll_rec 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.
> | starting_rec
> | Type: | Integer
> | Access: | Read
> | Mechanism: | By value
> | Usage: | Sequential record number (starting at 0) of record to begin list from. Records are returned sequentially from the table. Up to max_rpc_return_recs (Parameter table configuration value) are returned in each call.

> ### 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: | Coll_data_list_2
> Access: | Write
> Mechanism: | By reference
> Usage: | Pointer to a union. The union contains either a failure code or a pointer to a structure of type coll_list, 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: | Coll_list_2
> | Access: | Write
> | Mechanism: | By reference
> | Usage: | Start of linked list. Pointer to a structure of collection table record, and a forward pointer to the next node in the linked list. The following are the contents of this structure:
> |  | pNext
> |  | Type: | Coll_list_2
> |  | Access: | Write
> |  | Mechanism: | By value
> |  | Usage: | Start of linked list. Pointer to a structure of type coll_list.
> |  | coll_data
> |  | Type: | Coll_rec_2
> |  | Access: | Write
> |  | Mechanism: | By reference
> |  | Usage: | Collection table row. Collection table fields are described in Section 9.3.

## Description

> The ACMSMGMT_LIST_COLLECTIONS_2 procedure returns a linked list of collection table rows. The number of rows returned in a single call is bounded by the value of the Parameter table field max_rpc_return_recs. More than one call may be required to fetch all the rows. The selection record field starting_rec determines the table row to begin with. Records are returned sequentially from the table, beginning with the starting_rec row. Row numbering begins at 0.

> Entire table rows are returned. See Section 9.3 for a description of the fields in the coll_rec 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.

> If the end of the table is reached during execution of this procedure, MGMT_NOMORE_DATA is returned in the status field.

## Example

    int list_collection_data(int client_id,CLIENT *cl)
    {

       int rec_count = 0;
       coll_data_list_2  *coll;
       coll_link_2       *nl;
       static struct coll_sel_struct coll_rec;
       int status;
       char c_states[2][9] = {"enabled","disabled"};
       char c_entities[10][9] = {"unknown","*","acc","tsc","qti","cp","exc",
                                 "server","group","mgr"};
       char c_classes[6][8] = {"*","id","config","runtime","pool","error"};

       coll_rec.client_id = client_id;
    top:
       coll_rec.starting_rec = rec_count;

       coll = acmsmgmt_list_collections_2(&coll_rec,cl);

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

       if ((coll->status != MGMT_SUCCESS) && (coll->status != MGMT_NOMORE_DATA)) {
          printf("\n Call to get Collection data failed, returning status code
                 %d",coll->status);
            xdr_free(xdr_coll_data_list2, coll);
            free(coll);
          return(status);
       }

       for (nl = coll->coll_data_list_2_u.list; nl != NULL; nl = nl->pNext) {
           rec_count++;
           if (nl->coll_data.entity_name_s > 0)
              printf("\n Entity: %-9s  Name: %-32s  Class: %-9s
                     Collection State: %-9s",
                     c_entities[nl->coll_data.entity_type],
                     nl->coll_data.entity_name,
                     c_classes[nl->coll_data.collection_class],
                     c_states[nl->coll_data.collection_state]);
       }

       if (coll->status != MGMT_NOMORE_DATA)
          goto top;

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

> In the preceding example, the ACMSMGMT_LIST_COLLECTIONS_2 procedure is called to fetch the contents of the Collection table. If the call succeeds, the entity type, name, class, and collection state are printed for each row in the table. 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.18 ACMSMGMT_LIST_CP_2

ACMS Remote Manager clients call this procedure to obtain a list of Command Process (CP) table entries.

## Format

> ### cp_data_list_2 *acmsmgmt_list_cp_2(cp_sel_struct *sub_rec, CLIENT *cl)

## Parameters

> ### sub_rec

> Type: | Cp_sel_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.
> | proc_name
> | Type: | String
> | Access: | Read
> | Mechanism: | By value
> | Usage: | String that lists the OpenVMS process name for each CP.

> ### 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: | Cp_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 cp_data_list2, 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: | Cp_list_2
> | Access: | Write
> | Mechanism: | By reference
> | Usage: | Start of linked list. Pointer to a structure of CP table record, and a forward pointer to the next node in the linked list. The following are the contents of this structure:
> |  | pNext
> |  | Type: | Cp_list_2
> |  | Access: | Write
> |  | Mechanism: | By value
> |  | Usage: | Start of linked list. Pointer to a structure of type coll_list.
> |  | cp_data
> |  | Type: | Cp_rec_r_2
> |  | Access: | Write
> |  | Mechanism: | By reference
> |  | Usage: | CP table row. CP table fields are described in Section 9.4.

## Description

> The ACMSMGMT_LIST_CP_2 procedure returns a linked list of CP table rows. All CP table rows are returned in each call. Records are returned sequentially from the table, beginning at the start of the table.

> Entire table rows are returned. See Section 9.4 for a description of the fields in the cp_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 CP table are subject to reuse. Rows are assigned round-robin, and are not cleared until they have been reassigned. So some rows may contain data for inactive CPs. 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) CP, and to process the row accordingly.

## Example

    int list_cp_data(int client_id,CLIENT *cl)
    {
       static char c_all_cps[2] = "*";
       cp_data_list_2  *cp_data;
       cp_link_2       *nl;
       static struct cp_sel_struct sub_rec;
       int status;

       sub_rec.client_id = client_id;
       sub_rec.proc_name = c_all_cps;

       cp_data = acmsmgmt_list_cp_2(&sub_rec,cl);

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

       if (cp_data->status == MGMT_FAIL)  {
          if (cp_data->cp_data_list_2_u.rc == MGMT_NOMORE_DATA) {
             printf("\n No CP data found");
               xdr_free(xdr_cp_data_list_2, cp_data);
               free(cp data);
             return(MGMT_FAIL);
          }
          printf("\n Call to get CP data failed, returning status code %d",
                 cp_data->cp_data_list_2_u.rc);
          status = cp_data->cp_data_list_2_u.rc;
            xdr_free(xdr_cp_data_list_2, cp_data);
            free(cp_data);
          return(status);
       }

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

       for (nl = cp_data->cp_data_list_2_u.list; nl != NULL; nl = nl->pNext) {
           if (nl->cp_data.record_state == MGMT_INACTIVE)
              printf("\n INACTIVE ");
           else
              printf("\n          ");
           printf(" PID: %8X  Process Name: %-s",
                   nl->cp_data.pid,
                   nl->cp_data.process_name);
       }

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

> In the preceding example, the ACMSMGMT_LIST_CP_2 procedure is called to fetch the contents of the CP table. If the call succeeds, the state of the CP (if INACTIVE), its PID, and process 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