# Compaq ACMS for OpenVMS
Remote Systems Management Guide

Previous | Contents | Index

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

To determine the status of the call and the contents of the return record, first check the status field. The following are possible values for 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 user records have been returned.

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

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

## Example

    int list_users_data(int client_id,CLIENT *cl)
    {

       user_data_list  *user;
       user_link    *nl;
       static struct sub_id_struct sub_rec;
       int status;

       sub_rec.client_id = client_id;

       user = acmsmgmt_list_users_1(&sub_rec,cl);

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

       if ((user->status != MGMT_SUCCESS) && (user->status != MGMT_NOMORE_DATA)) {
          printf("\n Call to get User data failed, returning status code %d",
                 user->user_data_list_u.rc);
          status = user->user_data_list_u.rc;
            xdr_free(xdr_user_data_list, user);
            free(user);
          return(status);
       }

       for (nl = user->user_data_list_u.list; nl != NULL; nl = nl->pNext)
           printf("\n User %s is logged in from node %s",nl->user_data.uname,
                  nl->user_data.nodename);

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

> In the preceding example, the ACMSMGMT_LIST_USERS_1 procedure is called to fetch information about the users who have logged in to the Remote Manager. If the call succeeds, the name of the user and the node they logged in from are displayed. Otherwise, an error message is displayed. Note that the name displayed is the name by which the user is known to the server, and may be a proxy account. The example in Section 6.4.1 shows how to declare and initialize the input arguments to this procedure.

# 8.28 ACMSMGMT_REPLACE_SERVER_1

This procedure requests the Remote Manager to replace an ACMS procedure server in an ACMS application on the same node on which the Remote Manager is running.

## Format

> ### cmd_output_rec *acmsmgmt_replace_server_1(ser_sel_struct *sub_rec,CLIENT *cl)

## Parameters

> ### sub_rec

> Type: | Ser_sel_struct
> Access: | Read |
> Mechanism: | By reference |
> Usage: | Structure that contains client information and procedure server selection criteria. 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

> Type: | Cmd_output_rec
> Access: | Write
> Mechanism: | By reference
> Usage: | Pointer to a union. The union contains either a failure code or a structure of type cmd_rec, which points to a linked list containing status messages. The following are the contents of this union:
> | status
> | Type: | Integer
> | Access: | Write
> | Mechanism: | By value
> | Usage: | Failure return code.
> | rc
> | Type: | Integer
> | Access: | Write
> | Mechanism: | By value
> | Usage: | Failure return code.
> | data, data_warn
> | Type: | Cmd_rec
> | Access: | Write
> | Mechanism: | By value
> | Usage: | Structure containing the first node in a linked list of status messages (type dcl_list). The following are the contents of this structure:
> |  | 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 to have an ACMS procedure server replaced (stopped and started) in an application that is running on the same node on which the Remote Manager is running. The combination of appl_name and server_name in the input record determines which server will be replaced.

> This call executes synchronously. It does not return to the caller until the attempt to replace the server is complete. Any messages associated with an unsuccessful replacing of the server are returned in the cmd_output linked list.

> The data and data_warn structures contain identical data. If the operation fails, the status field of both structures will be MGMT_WARN; in this case, use the data_warn structure to fetch the status messages from the cmd_output linked list.

> If the operation is successful, the status field of both structures will be MGMT_SUCCESS. There are no status messages associated with a successful call.

> If the status field contains MGMT_FAIL, the call failed. There are no status messages returned; instead, the reason for the failure is contained in the rc field.

## Example

    int replace_server(int client_id,CLIENT *cl)
     {

       dcl_link    *nl;
       static char c_name_all[2] = "*";
       static char vr_read_server[] = "VR_READ_SERVER";
       static struct ser_sel_struct sub_rec;
       static cmd_output_rec *ret_struct;

       sub_rec.client_id = client_id;
       sub_rec.appl_name = c_name_all;
       sub_rec.server_name = vr_read_server;

       ret_struct = acmsmgmt_replace_server_1(&sub_rec,cl);

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

       if (ret_struct->status != MGMT_SUCCESS) {

       if (ret_struct->status != MGMT_WARN) {
          printf("\nCall to replace procedure server %s failed",
                 sub_rec.server_name);
          return(MGMT_FAIL);
       }

       printf("\n Call to replace procedure server %s completed with warnings or
              errors",sub_rec.server_name);

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

       else {
          printf("\nCall to replace procedure server %s was executed",
                 sub_rec.server_name);
          for (nl = ret_struct->cmd_output_rec_u.data.cmd_output; nl != NULL;
               nl = nl->pNext)
          printf("\n %s",nl->dcl_msg);
       }
          xdr_free(xdr_cmd_output_rec, ret_struct);
          free(ret_struct);
       return(0);
    }

> In the preceding example, the ACMSMGMT_REPLACE_SERVER_1 procedure is called to replace servers named VR_READ_SERVER in any application on the target node. If the call succeeds, all VR_READ_SERVER servers are replaced (stopped and started). Otherwise, any error messages associated with the failure are displayed. The example in Section 6.4.1 shows how to declare and initialize the input arguments to this procedure.

# 8.29 ACMSMGMT_RESET_LOG_1

This procedure requests the Remote Manager to close the current version of its log file and open a new one.

## Format

> ### int *acmsmgmt_reset_log_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: | Integer
> Access: | Write
> Mechanism: | By reference
> Usage: | Pointer to a status code containing a success or failure status code. MGMT_SUCCESS indicates success. Other values indicate failure.

## Description

> This procedure requests the Remote Manager to close the currently open version of its log and to open a new one. All subsequent log entries are posted to the new version, and the old version can be safely removed.

## Example

    int reset_log_data(int client_id,CLIENT *cl)
     {

       static struct sub_id_struct sub_rec;
       int *status;

       sub_rec.client_id = client_id;

       status = acmsmgmt_reset_log_1(&sub_rec,cl);

       if (!status) {
          printf("\n Call to reset log failed");
          return(MGMT_FAIL);
       }

       if (*status != MGMT_SUCCESS) {
          printf("\n Call to reset log failed with status %d",*status);
            free(status);
          return(MGMT_FAIL);
       }
       else
          printf("\n Call to reset log completed");
            free(status);
       return(0);
    }

> In the preceding example, the ACMSMGMT_RESET_LOG_1 procedure is called to close the current Remote Manager log and to open a new one. If the call succeeds, 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.30 ACMSMGMT_RESET_ERR_2

This procedure requests the Remote Manager to close the current version of the error log file and open a new one.

## Format

> ### int *acmsmgmt_reset_err_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: | Integer
> Access: | Write
> Mechanism: | By reference
> Usage: | Pointer to a status code containing a success or failure status code. MGMT_SUCCESS indicates success. Other values indicate failure.

## Description

> This procedure requests the Remote Manager to close the currently open version of the error log and to open a new one. All subsequent erro log entries are posted to the new version, and the old version can be safely removed.

## Example

    int reset_err_data(int client_id,CLIENT *cl)
     {

       static struct sub_id_struct sub_rec;
       int *status;

       sub_rec.client_id = client_id;

       status = acmsmgmt_reset_err_2(&sub_rec,cl);

       if (!status) {
          printf("\n Call to reset log failed");
          return(MGMT_FAIL);
       }

       if (*status != MGMT_SUCCESS) {
          printf("\n Call to reset log failed with status %d",*status);
            free(status);
          return(MGMT_FAIL);
       }
       else
          printf("\n Call to reset log completed");
            free(status);
       return(0);
    }

> In the preceding example, the ACMSMGMT_RESET_ERR_2 procedure is called to close the current error log and to open a new one. If the call succeeds, 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.

Previous | Next | Contents | Index