This procedure deletes entries from the Remote Manager Error Filter table. Error Filter table entries can also be added (see Section 8.4).

Format

int *acmsmgmt_delete_err_filter_2(err_del_rec *set_struct,CLIENT *cl2)

Parameters

set_struct

Type:	Err_del_rec
Access:	Read
Mechanism:	By reference
Usage:	Structure that contains the following client identification and Error Filter table 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.
	error_code
	Type:	Integer
	Access:	Read
	Mechanism:	By value
	Usage:	The type of ACMS entity the process is. Entity types are listed in Table 8-4.

cl2

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 deletes rows from the Error Filter table (see Section 9.5).

The Error Filter table is dynamic and does not have a fixed upper boundary. The size of the table fluctuates as entries are added and deleted. When a row becomes empty or unoccupied, it is removed and the remaining rows are renumbered.

Changes to the Error Filter table are processed immediately, and may affect more than one ACMS process. See Section 5.1 for a discussion of how the Error Filter table affects ACMS error logging.

Example

int delete_err_filter(int client_id,CLIENT *cl2) 
 { 
 
   int *status; 
   err_filter_config_rec_r_2 set_struct; 
 
   set_struct.client_id       = client_id; 
   set_struct.err_code        = 16638720; 
 
   status = acmsmgmt_delete_err_filter_2(&set_struct,cl2); 
 
   if (!status) { 
        printf("\n RPC Call to delete filter failed"); 
        return(MGMT_FAIL); 
   } 
 
   if (*status != MGMT_SUCCESS) { 
      printf("\n Call to delete error filter failed with status %d",*status); 
      free(status); 
      return(MGMT_FAIL); 
   } 
   else { 
      printf("\n Call to delete error filter was executed"); 
   } 
   free(status); 
   return(0); 
} 
      

In the preceding example, the acmsmgmt_delete_err_filter_2 procedure is called to delete a row from the Error Filter table. The example in Section 6.4.1 shows how to declare and initialize the input arguments to this procedure.

8.8 ACMSMGMT_DELETE_TRAP_1

Format

int *acmsmgmt_delete_trap_1(trap_del_rec *set_struct,CLIENT *cl)

Parameters

set_struct

Type:	Trap_del_rec
Access:	Read
Mechanism:	By reference
Usage:	Structure that contains the following client identification and Trap table 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.
	entity_type
	Type:	Integer
	Access:	Read
	Mechanism:	By value
	Usage:	The type of ACMS entity the process is. Entity types are listed in Table 8-4.
	entity_name
	Type:	Null-terminated string
	Access:	Read
	Mechanism:	By reference
	Usage:	Pointer to a character string containing a full or partial entity name. May contain wildcard characters (*, !).
	param_to_trap
	Type:	Integer
	Access:	Read
	Mechanism:	By value
	Usage:	The type of parameter to be monitored for trap conditions. Parameter types are listed in Table 8-8.

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 deletes rows from the Trap table (see Section 9.13).

Calls to this procedure must specify entity_type, entity_name, and param_to_trap. These fields must exactly match an existing record in the Trap table for the delete to be performed. Table 8-1 and Table 8-4 contain symbolic values used to populate the collection_class and entity_type fields; symbolic values to the param_to_trap field are described in Table 8-8.

Deletions from the Trap table are processed immediately and may affect more than one ACMS process. See Section 7.8 for a discussion of how to set SNMP traps.

Example

int delete_trap_data(int client_id,CLIENT *cl) 
 { 
 
   static char c_name_all[2] = "*"; 
   static trap_del_rec set_struct; 
   static int *status; 
   
   set_struct.client_id       = client_id 
   set_struct.entity_type     = MGMT_ACC; 
   set_struct.entity_name     = c_name_all; 
   set_struct.param_to_trap   = MGMT_EXISTS; 
 
   status = acmsmgmt_delete_trap_1(&set_struct,cl); 
 
   if (!status) { 
      printf("\n Call to delete trap failed"); 
      return(MGMT_FAIL); 
   } 
 
   if (*status != MGMT_SUCCESS) { 
      printf("\nCall to delete trap failed with status %d",*status); 
        free(status); 
      return(MGMT_FAIL); 
   } 
   else 
      printf("\nCall to delete trap was executed"); 
        free(status); 
      return(0); 
} 
 
      

In the preceding example, the ACMSMGMT_DELETE_TRAP_1 procedure is called to delete a row from the Trap table. The row to be deleted contains an entity type of ACC, an entity name of * (all), and a trap parameter of EXISTS. If the call succeeds, the trap is deleted from the Trap 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.9 ACMSMGMT_GET_ACC_2

Format

acc_rec_out_2 *acmsmgmt_get_acc_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:	Acc_rec_out_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

This procedure obtains class information about an ACC. The return pointer points to a record of type acc_rec_out_2, which contains a union consisting of either a failure return code or a pointer to an ACC record. See Section 9.2 for a description of the fields in the ACC 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_acc_data(int client_id,CLIENT *cl) 
 { 
 
   acc_rec_r_2      *accs; 
   acc_rec_out_2    *acc_rec; 
   static struct sub_id_struct sub_rec; 
   int status; 
 
   sub_rec.client_id = client_id; 
 
   acc_rec = acmsmgmt_get_acc_2(&sub_rec,cl); 
 
   if (!acc_rec) { 
      printf("\n RPC Call to get ACC data failed"); 
      return(MGMT_FAIL); 
   } 
 
   if (acc_rec->status != MGMT_SUCCESS) { 
      printf("\n Call to get ACC data failed, returning status code %d", 
             acc_rec->status); 
        xdr_free(xdr_acc_rec_out_2, acc_rec); 
        free(acc_rec); 
      return(status); 
   } 
   
   accs = &acc_rec->acc_rec_out_2_u.acc_rec; 
 
      printf("\n ACC version is %s",accs->acms_version); 
        xdr_free(xdr_acc_rec_out_2, acc_rec); 
        free(acc_rec); 
      return(0); 
 
} 
 
      

In the preceding example, the ACMSMGMT_GET_ACC_2 procedure is called to fetch ACC management information. If the call succeeds, the ACC version is printed from the retreived 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.10 ACMS$MGMT_GET_CREDS

Format

int acms$mgmt_get_creds(char *server_node,char *user_name, int *client)

Parameters

server_node

Type:	String
Access:	Read
Mechanism:	By reference
Usage:	Name of the node the server that issued the client ID was running on; the node that will be accessed. Client_id is valid only for the server that issued it.

user_name

Type:	String
Access:	Read
Mechanism:	By reference
Usage:	Name of the user the client ID was issued to, and on whose behalf the client ID is used. The name may the same as or different than the account name of the client process.

client

Type:	Integer
Access:	Write
Mechanism:	By reference
Usage:	The client ID to be used for the target user on the target server node. The client ID is valid only for the client process that created it.

Return Value

Type:	Integer
Access:	Write
Mechanism:	By value
Usage:	The completion status of the call. The following are possible return values:
	Value	Description
	MGMT_SUCCESS	Client ID was fetched; credentials verified.
	MGMT_NO_NODELOGICAL	Can't translate UCX$INET_HOST logical name to get local node name.
	MGMT_NO_CREDS_FILE	Credentials file was not found.
	MGMT_CREDS_DATA_ERR	Credentials file is corrupt.
	MGMT_WRONG_PID	PID in credentials file doesn't match client process's PID.
	MGMT_WRONG_NODE	Node name in credentials file doesn't match server_node argument.

Description

Clients call this procedure to fetch a previously created client ID from an encrypted credentials file. Credentials files can be created only by the ACMSMGR LOGIN command. They are stored in the directory pointed to by the logical name ACMS$MGMT_CREDS_DIR (or SYS$LOGIN if ACMS$MGMT_CREDS_DIR is not defined). Credentials files are named using the following format:

user-name_pid_target-node_current-node.dat

In this format:

• user-name must match the user_name argument string.
• pid must match the PID of the client process.
• target-node must match the server_node argument string.
• current-node must be the local node name (as determined by the logical name UCX$INET_HOST).

Note For credentials information to be created, the client process must first execute the login command of the ACMSMGR utility. The only way to create credentials files is by using the ACMSMGR utility.

If the credentials file cannot be located, opened, and read, an error is returned. Once opened and read, the credentials in the file are verified. If the credentials are acceptable, the client_id field is populated and the procedure returns a status that indicates success.

This procedure is statically linked and locally executed.

Example

#include <rpc/rpc.h> 
#include string 
#include "acmsmgmt_rpc.h" 
 
CLIENT *cl; 
char sname[] = "sparks"; 
char *username_p, username[13] = ""; 
int client_id; 
int status; 
 
int acms$mgmt_get_creds(); 
 
int main () 
{ 
 
    /* if the logical is defined, credential information will be used */ 
    username_p = getenv("ACMS$MGMT_USER"); 
    if (username_p) 
          strcpy(username,username_p); 
 
    /* establish an rpc connection to the server */ 
    cl = clnt_create(sname, ACMSMGMT_RPC, ACMSMGMT_VERSION, "tcp"); 
 
    /* if the connection was established */ 
    if (cl != NULL) { 
 
        /* create a security context */ 
        cl->cl_auth = authunix_create_default(); 
        client_id = 0; 
 
        /* optionally, get credentials for this user & server */ 
        if (strlen(username)) 
           status = acms$mgmt_get_creds(sname,username,&client_id); 
 
      } 
 
return(1); 
} 
 
      

The preceding example is a program that performs initialization for an ACMS Remote Manager client. The program calls the acms$mgmt_get_creds procedure to obtain the client ID for the user whose name is defined by the logical name ACMS$MGMT_USER on the node SPARKS.