Compaq ACMS for OpenVMS
Remote Systems Management Guide
Previous Contents Index

7.17 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_id_rec, CLIENT *cl)

Parameters

sub_id_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

proc_data_list

Type: Proc_data_list
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 proc_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: 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 7.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: 4
      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

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 8). For each process, the Remote Manager populates a proc_data record.

Note that some entity tables may contain rows with inactive data, that is, data for processes that are no longer active. The data in these rows may or may not be interesting to the caller. To distinguish active and inactive processes, the Remote Manager sets the record_state field to MGMT_VALID for active processes and to MGMT_INACTIVE for inactive processes. The caller is responsible for checking this field and taking appropriate action.

The collection_states field is a simple array of four integers. Each array element contains either a 1 (if the collection class is enabled) or a 0 (if the collection class is disabled). Array elements are positional, as described in the Return Value section.

Like other procedures that return linked lists (see Section 5.5.1 for a detailed example of linked-list processing), the return parameter is a union containing either a failure status code or a linked list of records.

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:

If the status field value is MGMT_SUCCESS, a linked list has been returned. The linked list contains a structure containing the process data, and a forward pointer. By following the forward pointer, all the records in the list can be retrieved.

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 list_process_data(int client_id,CLIENT *cl) 
{ 
 
   proc_data_list  *proc; 
   proc_link     *nl; 
   static struct sub_id_struct sub_rec; 
 
   sub_rec.client_id = client_id; 
 
   proc = acmsmgmt_list_proc_1(&sub_rec,cl); 
 
   if (!proc) { 
      printf("\n RPC Call to get process data failed"); 
      return(MGMT_FAIL); 
   } 
 
   if ((proc->status != MGMT_SUCCESS) && (proc->status != MGMT_NOMORE_DATA)) { 
       printf("\n Call to get process data failed, returning status code 
%d",proc->proc_data_list_u.rc); 
       return(MGMT_FAIL); 
   } 
   
   for (nl = proc->proc_data_list_u.list; nl != NULL; nl = nl->pNext) { 
       if (nl->proc_data.record_state == MGMT_INACTIVE) 
           printf("\n INACTIVE "); 
       else 
           printf("\n          "); 
       printf(" PID: %8X  Process Name: 
%s",nl->proc_data.pid,nl->proc_data.process_name); 
   } 
 
   printf("\n End of data"); 
 
   return(0); 
}

In the preceding example, the acmsmgmt_list_proc_1 procedure is called to fetch information about collection states from all processes accessible to the Remote Manager. If the call succeeds, the name of the process, along with its state is displayed (inactive processes have that string printed before the process name). 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.18 ACMSMGMT_LIST_SERVER_1

ACMS Remote Manager clients call this procedure to obtain a list of procedure server table (Server table) entries.

Format

ser_data_list = acmsmgmt_list_server_1(ser_sel_struct *ser_sel, CLIENT *cl)

Parameters

ser_sel

Type: Ser_sel_struct
Access: Read  
Mechanism: By reference  
Usage: Structure that contains client information and procedure server 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.
     
  server_name
  Type: Null-terminated string
  Access: Read
  Mechanism: By reference
  Usage: A pointer to a procedure server 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

ser_data_list

Type: Ser_data_list
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 ser_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: Ser_list
  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: Proc_list
    Access: Write
    Mechanism: By value
    Usage: Start of linked list. Pointer to a structure of type coll_list.
         
    ser_data
    Type: Ser_rec_r
    Access: Write
    Mechanism: By reference
    Usage: Server table row. Server table fields are described in Section 8.10.

Description

The acmsmgmt_list_ser_1 procedure returns a linked list of Server table rows. All matching Server table rows are returned in each call. Matching is performed first on application name, and then on server name. Therefore, all matching servers for all matching applications are returned.

Entire table rows are returned. See Section 8.10 for a description of the fields in the ser_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. The Remote Manager attempts to retrieve server information 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_ser_data(int client_id,CLIENT *cl) 
{ 
 
   static char c_all_appls[2] = "*"; 
   ser_data_list  *ser_data; 
   ser_link      *nl; 
 
   static struct ser_sel_struct sub_rec; 
 
   sub_rec.client_id = client_id; 
   sub_rec.appl_name = c_all_appls; 
   sub_rec.server_name = c_all_appls; 
 
   ser_data = acmsmgmt_list_server_1(&sub_rec,cl); 
 
   if (!ser_data) { 
      printf("\n RPC Call to get ser data failed"); 
      return(MGMT_FAIL); 
   } 
 
   if (ser_data->status == MGMT_FAIL)  { 
       if (ser_data->ser_data_list_u.rc == MGMT_NOMORE_DATA) { 
          printf("\n No SER data found"); 
          return(MGMT_FAIL); 
       }   
       printf("\n Call to get ser data failed, returning status code 
%d",ser_data->ser_data_list_u.rc); 
       return(MGMT_FAIL); 
   } 
 
   if (ser_data->status == MGMT_WARN) 
       printf("\n ** Warning, some data may be from inactive processes **"); 
   
   for (nl = ser_data->ser_data_list_u.list; nl != NULL; nl = nl->pNext) { 
       if (nl->ser_data.record_state == MGMT_INACTIVE) 
          printf("\n INACTIVE "); 
       else 
          printf("\n          "); 
       printf(" Application : %-32s Server: %-s", 
               nl->ser_data.appl_name, 
               nl->ser_data.server_name); 
   } 
 
   printf("\n End of data"); 
 
   return(0); 
}

In the preceding example, the acmsmgmt_list_server_1 procedure is called to fetch the contents of the Server tables for all applications on the target node. If the call succeeds, the state of the server (if inactive), the name of the application it belongs to, and the name of the server are displayed for each table row returned. 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.

Previous Next Contents Index