# Compaq ACMS for OpenVMS
Remote Systems Management Guide

Previous | Contents | Index

This call executes synchronously. It does not return to the caller until the attempt to stop the system is complete. Any messages associated with an unsuccessful stop of the system 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. No status messages are associated with a successful call.

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

## Example

    int stop_acc(int client_id,CLIENT *cl)
    {
       dcl_link    *nl;
       static acc_shutdown_rec stop_struct;
       cmd_output_rec *ret_struct;

       stop_struct.client_id = client_id;
       stop_struct.cancel_sw  = 1;

       ret_struct = acmsmgmt_stop_acc_1(&stop_struct,cl);

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

       if (ret_struct->status != MGMT_SUCCESS) {
          if (ret_struct->status != MGMT_WARN) {
             printf("\nCall to stop ACMS ACC failed with status %d",
                    ret_struct->status);
               xdr_free(xdr_cmd_output_rec, ret_struct);
               free(ret_struct);
             return(MGMT_FAIL);
       }

            printf("\n Call to stop ACMS ACC completed with warnings or errors");

     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 stop ACMS ACC was executed");
            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_STOP_ACC_1 procedure is called to stop the ACMS run-time system on the target node. The system is stopped abruptly (/CANCEL), terminating any in-process tasks. If the call succeeds, the ACMS system is stopped on the target node. 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.49 ACMSMGMT_STOP_EXC_1

This procedure requests that the Remote Manager stop the ACMS system.

## Format

> ### cmd_output_rec *acmsmgmt_stop_exc_1(exc_shutdown_rec *stop_struct,CLIENT *cl)

## Parameters

> ### stop_struct

> Type: | Exc_shutdown_rec
> Access: | Read |
> Mechanism: | By reference |
> Usage: | Structure that contains the following client identification and Application Execution Controller (EXC) control 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.
> | cancel_sw
> | Type: | Integer
> | Access: | Read
> | Mechanism: | By value
> | Usage: | Indicates whether the application should be stopped immediately (cancel_sw = 1), or whether currently executing tasks should be allowed to complete first (cancel_sw = 0).
> | appl_name
> | Type: | Null-terminated string
> | Access: | Read
> | Mechanism: | By reference
> | Usage: | Name of the application to be stopped.

> ### 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 record that contains a union consisting of 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 shuts down an ACMS application on the same node on which the Remote Manager is running. Fields in the input argument determine which application to stop (appl_name) and how the application will be stopped. If the value for cancel_sw is 1, currently executing tasks are cancelled, and the application is stopped. If the value for cancel_sw is 0, currently executing tasks are allowed to complete before the application is shut down.

> This call executes synchronously. It does not return to the caller until the attempt to stop the application is complete. Any messages associated with an unsuccessful stop of the system 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 structure 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. No status messages are associated with a successful call.

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

## Example

    int stop_exc(int client_id,CLIENT *cl)
    {
       dcl_link    *nl;
       static char c_appl_name[] = "VR_APPL";
       static exc_shutdown_rec stop_struct;
       cmd_output_rec *ret_struct;

       stop_struct.client_id = client_id;
       stop_struct.cancel_sw  = 1;
       stop_struct.appl_name  = c_appl_name;

       ret_struct = acmsmgmt_stop_exc_1(&stop_struct,cl);

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

       if (ret_struct->status != MGMT_SUCCESS) {

       if (ret_struct->status != MGMT_WARN) {
          printf("\nCall to stop ACMS EXC failed with status %d",
                 ret_struct->status);
            xdr_free(xdr_cmd_output_rec, ret_struct);
            free(ret_struct);
          return(MGMT_FAIL);
       }

       printf("\n Call to stop ACMS EXC completed with warnings or errors");

            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 stop ACMS EXC was executed");
            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_STOP_EXC_1 procedure is called to stop an application named VR_APPL on the target node. If the call succeeds, the VR_APPL application is stopped on the target node. 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.50 ACMSMGMT_STOP_QTI_1

This procedure requests that the Remote Manager stop a Queued Task Initiator (QTI) on the same node on which the Remote Manager is running.

## Format

> ### cmd_output_rec *acmsmgmt_stop_qti_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: | Cmd_output_rec
> Access: | Write
> Mechanism: | By reference
> Usage: | Pointer to a record that contains a union consisting of 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 stop an ACMS QTI on the same node on which the Remote Manager is running.

> This call executes synchronously. It does not return to the caller until the attempt to stop the QTI is complete. Any messages associated with an unsuccessful stop of the QTI 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. No status messages are associated with a successful call.

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

## Example

    int stop_qti(int client_id,CLIENT *cl)
    {
       dcl_link    *nl;
       static struct sub_id_struct sub_rec;
       cmd_output_rec *ret_struct;

       sub_rec.client_id = client_id;

       ret_struct = acmsmgmt_stop_qti_1(&sub_rec,cl);

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

       if (ret_struct->status != MGMT_SUCCESS) {

     if (ret_struct->status != MGMT_WARN) {
                printf("\nCall to stop ACMS QTI failed with status %d",
                       ret_struct->status);
                  xdr_free(xdr_cmd_output_rec, ret_struct);
                  free(ret_struct);
                return(MGMT_FAIL);
       }

            printf("\n Call to stop ACMS QTI completed with warnings or errors");

            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 stop ACMS QTI was executed");
            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_STOP_QTI_1 procedure is called to stop the Queued Task Initiator (QTI) on the target node. If the call succeeds, the QTI is stopped on the target node. 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.

Previous | Next | Contents | Index