This procedure requests that the Remote Manager start the ACMS$TRACE_MONITOR process. The ACMS$TRACE_MONITOR process is an intermediate process used by the Remote Manager to communicate with ACMS run-time processes to enable and disable collections.

Format

int *acmsmgmt_start_trace_monitor_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 status value returned. If the value is NULL or MGMT_SUCCESS, the RPC has succeeded. If the value is neither NULL nor MGMT_SUCCESS, the call failed and the value pointed to is the reason for failure.

Description

This procedure requests that the Remote Manager start the ACMS$TRACE_MONITOR process on the target node. The ACMS$TRACE_MONITOR process is an intermediate process used by the Remote Manager to communicate with ACMS run-time processes to enable and disable collections.

In general, external entities do not require a startup and shutdown request of the trace monitor process. The Remote Manager starts the trace monitor during process initialization and stops it during process shutdown. Additionally, the Remote Manager starts the trace monitor anytime it is needed (if it is not already started). Once started, the trace monitor continues to run until the Remote Manager shuts down.

After issuing the start command to the trace monitor, the Remote Manager waits for a period of up to trace_start_wait_time (a Parameter table parameter that is dynamic and expressed in seconds). If the trace monitor fails to start during that period, the Remote Manager returns an error to the caller.

Example

int start_trace(int client_id,CLIENT *cl) 
{ 
   int *status; 
   static struct sub_id_struct sub_rec; 
 
   sub_rec.client_id = client_id; 
 
   status = acmsmgmt_start_trace_monitor_1(&sub_rec,cl); 
 
   if (!status) { 
      printf("\nStartup of Trace Monitor has failed"); 
      return(MGMT_FAIL); 
   } 
 
   if (*status != MGMT_SUCCESS) { 
      printf("\nStartup of Trace Monitor has failed with return code %d", 
             *status); 
      return(*status); 
   } 
 
   printf("\nTrace Monitor has been started "); 
     free(status); 
   return(MGMT_SUCCESS); 
} 
 
      

In the preceding example, the ACMSMGMT_START_TRACE_MONITOR_1 procedure is called to start the ACMS$TRACE_MON process on the target node. If the call succeeds, the process is 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.46 ACMSMGMT_START_TSC_1

Format

cmd_output_rec *acmsmgmt_start_tsc_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 that an ACMS TSC be started 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 start the TSC is complete. Any messages associated with an unsuccessful start of the TSC 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 start_tsc(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_start_tsc_1(&sub_rec,cl); 
 
   if (!ret_struct) { 
      printf("\n Call to start TSC failed"); 
      return(MGMT_FAIL); 
   } 
 
   if (ret_struct->status != MGMT_SUCCESS) { 
 
      if (ret_struct->status != MGMT_WARN) { 
         printf("\nCall to start ACMS TSC 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 start ACMS TSC 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 start ACMS TSC 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_START_TSC_1 procedure is called to start the terminal subsystem on the target node. If the call succeeds, the terminal subsystem is started 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.47 ACMSMGMT_STOP_1

Format

int *acmsmgmt_stop_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 status value returned. If the value is NULL or MGMT_SUCCESS, the RPC has succeeded. If the value is neither null nor MGMT_SUCCESS, the call failed and the value pointed to is the reason for failure.

Description

This procedure shuts down the Remote Manager server on the target node. As part of shutdown, the RPC interface is stopped, which may result in a NULL pointer being returned to the caller. A NULL pointer in this case signals success of the shutdown request.

Note that the success of this procedure does not guarantee that the Remote Manager server has actually shut down. It guarantees only that the shutdown has been requested.

Example

int stop_manager(int client_id,CLIENT *cl) 
{ 
   static int *status; 
   static struct sub_id_struct sub_rec; 
   sub_rec.client_id = client_id; 
 
   status = acmsmgmt_stop_1(&sub_rec,cl); 
 
   if (!status) { 
      printf("\nServer shutdown has been requested"); 
      return(0); 
   } 
 
   if (*status != MGMT_SUCCESS) { 
      printf("\n Call to stop server failed with status %d",*status); 
      return(MGMT_FAIL); 
   } 
 
   printf("\n Server shutdown has been requested"); 
 
 return(0); 
} 
 
      

In the preceding example, the ACMSMGMT_STOP_1 procedure is called to request shutdown of the ACMS Remote Manager. A message is displayed indicating the success or failure of the operation. The example in Section 6.4.1 shows how to declare and initialize the input arguments to this procedure.

8.48 ACMSMGMT_STOP_ACC_1

Format

cmd_output_rec *acmsmgmt_stop_acc_1(acc_shutdown_rec *stop_struct,CLIENT *cl)

Parameters

stop_struct

Type:	Acc_shutdown_rec
Access:	Read
Mechanism:	By reference
Usage:	Structure that contains the following client identification and ACC 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 system should be stopped immediately (cancel_sw = 1), or whether currently executing tasks should be allowed to complete first (cancel_sw = 0).

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 the ACMS run-time system on the same node on which the Remote Manager is running. Fields in the input argument determine how the ACMS system will be stopped. If the value for cancel_sw is 1, currently executing tasks are cancelled, and the system is stopped. If the value for cancel_sw is 0, currently executing tasks are allowed to complete before the system is shut down.

---

Previous

Next

Contents

Index