| Previous | Contents | Index |
Set procedures are available for many of the ACMS Remote Manager tables. Set procedures allow you to modify ACMS entity and Remote Manager configuration information. As Table 6-4 shows, a separate set procedure is available for each entity and table.
| Procedure | Description |
|---|---|
| acmsmgmt_set_acc_2 | No keys; only 1 ACC per node. |
| acmsmgmt_set_coll_2 | Key value is entity, ID, and class. |
| acmsmgmt_set_cp_2 | No keys; only 1 CP per node. |
| acmsmgmt_set_exc_2 | Key value is application name. |
| acmsmgmt_set_interface_1 | Key value is interface name. |
| acmsmgmt_set_param_2 | No keys; only one row in the parameter table. |
| acmsmgmt_set_qti_2 | No keys; only 1 QTI per node. |
| acmsmgmt_set_server_1 | Key value is application name and server name. |
| acmsmgmt_set_trap_1 | Key value is entity, ID, and parameter. |
| acmsmgmt_set_tsc_2 | No keys; only 1 TSC per node. |
For Entity tables, set procedures allow fields to be modified for a particular entry. A unique key value must be provided to identify the particular table row to be updated for tables with more than one row. Only configuration class fields can be modified in entity tables.
For the Trap and Collection tables, add and delete procedures (described in Section 6.8 and Section 6.9) are available along with set procedures. Each procedure requires a unique key value.
For all tables, some or all fields in a row can be modified in a single call. The Remote Manager scans the input record for uninitialized fields (that is, fields that are not set to the default value of -1); if a field contains an initialized value, the Remote Manager attempts to apply the update. The corresponding field in the return record is updated with the completion status of the update. Updates are applied serially, but the Remote Manager attempts to update all initialized fields regardless of the outcome of any individual update. The exception to this processing is if an internal error occurs, in which case processing is aborted.
All calls are synchronous.
See Chapter 8 for details about each call.
6.7.1 Set Example
The following example code shows how a client program calls the acmsmgmt_set_param_2 procedure to change the values of the proc_mon_interval and mss_coll_interval parameters.
This example assumes client initialization has been performed as described in Section 6.4.
int set_param_data(int client_id,CLIENT *cl)
{
int x = 0;
int y = 0;
static param_config_rec2 set_struct;
param_status_rec2 *ret_struct;
static int *status;
/* initialize input argument; values < 0 are not processed
by the server */
memset(&set_struct,-1,sizeof(set_struct));
/* establish the client id */
set_struct.client_id = client_id;
set_struct.params.proc_mon_interval = 60;
set_struct.params.mss_coll_interval = 60;
ret_struct = acmsmgmt_set_param_2(&set_struct,cl);
if (!ret_struct) {
printf("\nCall to modify parameters failed");
return(MGMT_FAIL);
}
if (ret_struct->status != MGMT_SUCCESS) {
if (ret_struct->status != MGMT_WARN) {
printf("\nCall to modify parameters failed, returning %d",
ret_struct->status);
status=ret_struct->status;
xdr_free(xdr_param_status_rec2, ret_struct);
free(ret_struct);
return(MGMT_FAIL);
}
if (ret_struct->param_status_rec_u.data.proc_mon_interval != MGMT_SUCCESS)
printf("\n Call to modify proc_mon_interval failed");
if (ret_struct->param_status_rec_u.data.mss_coll_interval != MGMT_SUCCESS)
printf("\n Call to modify mss_coll_interval failed");
xdr_free(xdr_param_status_rec2, ret_struct);
free(ret_struct);
return(MGMT_FAIL);
}
else
printf("\n Call to update parameters successful");
xdr_free(xdr_param_status_rec2, ret_struct);
free(ret_struct);
return(0);
}
|
In this example, note that the input argument (set_struct) is initialized to negative values prior to the call. The Remote Manager will attempt to apply updates for any positive values found; negative values are ignored.
Following the call to the update routine, the return record pointer is
tested to ensure that it is not NULL (that is, that the call
completed). Then individual return codes are tested to determine the
status of the updates. The first status check (ret_rec->status)
determines the overall call status. For instance, security violations
will be recorded in this field. If that status field contains a failure
code, no updates were attempted. If that status field contains
MGMT_SUCCESS, updates were attempted for the two fields. The subsequent
status checks in the return record determine the outcome of those
updates.
6.8 Delete Procedures
Delete procedures are available for the Collection, Error Filter, and Trap tables. Delete procedures allow you to remove rows from the corresponding table. As Table 6-5 shows, a separate delete procedure is available for each of these tables.
The delete procedures require an input record with key data to be passed by the caller. A simple status code is returned indicating the success or failure of the operation.
All calls are synchronous.
See Chapter 8 for details about each call.
| Procedure | Description |
|---|---|
| acmsmgmt_delete_collection_1 | Key value is entity, ID, and class. |
| acmsmgmt_delete_err_filter_2 | Key value is message code. |
| acmsmgmt_delete_trap_1 | Key value is entity, ID, and parameter. |
The following example code shows how a client program calls the acmsmgmt_delete_collection_1 procedure to remove a collection row.
This example assumes that client initialization has been performed as described in Section 6.4.
int del_coll_data(int client_id,CLIENT *cl)
{
static int *status;
static coll_del_rec set_struct;
static char ent_name[MGMT_S_ENTITY_NAME];
set_struct.client_id = client_id;
set_struct.entity_type = MGMT_ACC;
strcpy(ent_name,"*");
set_struct.entity_name = ent_name;
set_struct.collection_class = MGMT_CLASS_ALL;
status = acmsmgmt_delete_collection_1(&set_struct,cl);
if (!status) {
printf("\n Call to delete collection failed");
return(MGMT_FAIL);
}
if (*status != MGMT_SUCCESS) {
printf("\nCall to delete collection failed with status %d",*status);
return(MGMT_FAIL);
}
else
printf("\nCall to delete collection was executed");
free(status)
return(0);
}
|
In this example, the input record is prepared with key information, and
then the call to delete the row is performed. Following the call to the
delete routine, the value pointed by status is checked for success or
failure. In either event, a message is printed out indicating the
completion status of the call.
6.9 Add Procedures
Add procedures are available for the Collection, Error Filter, and Trap tables. Add procedures provide the ability to add rows to the corresponding table. As shown in Table 6-6, a separate add procedure is available for each of these tables.
The add procedures require an input record with an entire table row, including unique key data to be passed by the caller. The Remote Manager validates the input fields before adding the record, including checking for duplicate keys. A record is returned with an overall status code indicating the success or failure of the operation, and with individual status codes for each field indicating which fields are invalid.
All calls are synchronous.
See Chapter 8 for details about each call.
| Procedure | Description |
|---|---|
| acmsmgmt_add_collection_2 | Key value is entity, ID, and class. |
| acmsmgmt_add_err_filter_2 | Key value is node and message code. |
| acmsmgmt_add_trap_1 | Key value is entity, ID, and parameter. |
The following example code shows how a client program calls the acmsmgmt_add_collection_2 procedure to add a collection row.
This example assumes client initialization has been performed as described in Section 6.4.
int add_collection_data(int client_id,CLIENT *cl)
{
static char c_name_all[2] = "*";
static coll_config_rec_2 set_struct;
struct coll_status_rec_2 *status_rec;
set_struct.client_id = client_id;
set_struct.coll.entity_type = MGMT_ACC;
set_struct.coll.entity_name = c_name_all;
set_struct.coll.collection_class = MGMT_CLASS_ALL;
set_struct.coll.collection_state = MGMT_STATE_ENABLED;
status_rec = acmsmgmt_add_collection_2(&set_struct,cl);
if (!status_rec) {
printf("\n Call to add collection record failed");
return(MGMT_FAIL);
}
if (status_rec->status == MGMT_WARN) {
printf("\nThe following fields are invalid: ");
if (status_rec->coll_status_rec_2_u.data_warn.entity_type == MGMT_FAIL)
printf("\n entity_type");
if (status_rec->coll_status_rec_2_u.data_warn.collection_class
== MGMT_FAIL)
printf("\n collection_class");
if (status_rec->coll_status_rec_2_u.data_warn.collection_state
== MGMT_FAIL)
printf("\n coll_state");
return(0);
}
else if (status_rec->status != MGMT_SUCCESS) {
printf("\nCall to add collection failed with status",
status_rec->coll_status_rec_2_u.rc);
xdr_free(xdr_coll_status_rec_2,status_rec);
free(status_rec);
return(0);
}
else
printf("\nCall to add collection was executed");
xdr_free(xdr_coll_status_rec_2,status_rec);
free(status_rec);
return(1);
}
|
In this example, the input record is prepared with key and data values, and then the call to add the row is performed.
Following the call to the add routine, the return record pointer is tested to ensure that it is not NULL (that is, that the call completed). Then the overall status code (status_rec->status) is checked to determine whether the add was performed.
A status value of MGMT_WARN indicates that some fields were in error, so individual return codes are tested to determine which fields were invalid.
A status value other than MGMT_WARN or MGMT_SUCCESS means a general
error occurred. A value of MGMT_SUCCESS means the record was added.
6.10 Start, Stop, and Replace Procedures
These three types of procedures are similar in the way they are called and in the data that is returned to them, even though they do very different operations. Start and stop procedures are used to start or stop various ACMS processes; the replace procedure is used to replace a running procedure server in an application.
An exception is the call to the acmsmgmt_stop_1 procedure, which requests the Remote Manager to shut down. For more information about the acmsmgmt_stop_1 procedure, see Chapter 8.
For the rest of the start, stop, and replace procedures, an input record, which contains key data or startup or shutdown qualifier flags, is provided by the caller; the return data contains a status code and a linked list of status messages. Status messages are generated by ACMSOPER and are returned in their entirety. (Linked-list processing is illustrated in Section 6.6.1.)
All calls are synchronous.
See Chapter 8 for details about each call.
| Procedure | Description |
|---|---|
| acmsmgmt_replace_server_1 | Key is application name and server name. |
| acmsmgmt_start_acc_1 | No keys; specify auditing, QTI, and terminal disposition. |
| acmsmgmt_start_exc_1 | Key is application name; no startup qualifiers. |
| acmsmgmt_start_qti_1 | No keys or qualifiers. |
| acmsmgmt_start_trace_monitor_1 | No keys or qualifiers. |
| acmsmgmt_start_tsc_1 | No keys or qualifiers. |
| acmsmgmt_stop_1 | No keys or qualifiers. |
| acmsmgmt_stop_acc_1 | No keys; specify cancel disposition. |
| acmsmgmt_stop_exc_1 | Key is application name; specify cancel disposition. |
| acmsmgmt_stop_qti_1 | No keys or qualifiers. |
| acmsmgmt_stop_trace_monitor_1 | No keys or qualifiers. |
| acmsmgmt_stop_tsc_1 | No keys or qualifiers. |
The following example code shows how a client program calls the acmsmgmt_start_acc_1 procedure to start ACMS on a remote node. In this example, the QTI and TSC are started along with the system, and system auditing is enabled.
This example assumes client initialization has been performed as described in Section 6.4.
int start_acc(int client_id,CLIENT *cl)
{
dcl_link *nl;
static acc_startup_rec start_struct;
static cmd_output_rec *ret_struct;
start_struct.client_id = client_id;
start_struct.audit_sw = 1;
start_struct.qti_sw = 1;
start_struct.terminals_sw = 1;
ret_struct = acmsmgmt_start_acc_1(&start_struct,cl);
if (!ret_struct) {
printf ("\n Call to start ACMS system failed");
return(MGMT_FAIL);
}
if (ret_struct->status != MGMT_SUCCESS) {
if (ret_struct->status != MGMT_WARN) {
printf("\nCall to start ACMS system failed with status %d",
ret_struct->status);
xdr_free(xdr_cmd_output_rec, ret_struct);
free(ret_struct);
return(0);
}
printf("\n Call to start ACMS system 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 system 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 this example, the input record is prepared with qualifier data, and then the call to start the system is performed. Auditing is enabled, and QTI and TSC will be started with the sytem.
The return value from the calls to the start, stop (except acmsmgmt_stop_1), and replace procedures is a pointer to a union. If the pointer returned is NULL, the call has failed. RPC error checking must be used to determine the cause of the error. If a valid pointer is returned, it points to a structure containing a union with the following structure:
union cmd_output_rec switch (int status) {
case MGMT_WARN:
cmd_rec data_warn;
case MGMT_SUCCESS:
cmd_rec data;
case MGMT_FAIL:
int rc;
default:
void;
};
|
The status field determines which structure is being returned. If the status is equal to MGMT_FAIL, the rc field is returned. The rc field contains a status code indicating the reason for failure.
If the status field is not equal to MGMT_WARN or MGMT_SUCCESS, a pointer to a linked list has been returned. The linked list contains a text field and a forward pointer. By following the forward pointers, all the records in the list can be retrieved. Section 6.6.1 illustrates how to follow the linked list.
In either case, the example code prints out the contents of all the strings in the linked list. These strings are status messages returned by ACMSOPER.
Programmers who want to access and maintain the ACMS Remote Manager from their own programs can use the following two interfaces:
This chapter discusses the SNMP interface. Programmers who are familiar with SNMP console programming can use this information when writing routines that interact with the ACMS Remote Manager using the SNMP protocol. The information in this chapter is also useful for programmers who are integrating the ACMS Remote Manager with other enterprise management packages through the SNMP protocol.
The ACMS Remote Manager implements the management information base (MIB) for SNMP. To access ACMS MIB information through SNMP, you must have an SNMP-enabled console (such as PATROL® from BMC®) or you can use an SNMP MIB browser such as the one provided by Compaq TCP/IP Services for OpenVMS, which includes the TCPIP$SNMP_REQUEST.EXE utility.
Alternatively, you can write your own SNMP interface. For more
information about programming SNMP, refer to Windows NT SNMP
by James D. Murray, published by O'Reilly & Associates, Inc.,
Sebastopol, CA.
7.1 SNMP Overview
The ACMS Remote Manager implements a MIB for ACMS. When the SNMP interface is enabled, either during or after Remote Manager process startup, it registers the ACMS subtree with the local SNMP master agent. SNMP console requests go first to the SNMP master agent (provided by the installed TCP/IP software, such as Compaq TCP/IP Services for OpenVMS), which in turn delivers them to the ACMS Remote Manager. Figure 7-1 illustrates the SNMP interface with the ACMS Remote Manager.
Figure 7-1 SNMP Program Interface with Remote Manager
Communications between the SNMP interface and the master agent use the eSNMP protocol. This protocol is transparent to SNMP consoles.
The ACMS Remote Manager provides management information to SNMP management platforms in response to snmp_get and snmp_getnext messages. Management platforms can modify many management data elements by sending the appropriate snmp_set message. If any traps have been configured, the ACMS Remote Manager will generate SNMP traps when the Remote Manager detects a trap condition (for example, when an ACMS process starts or stops).
All Management table fields are available to SNMP management applications through get operations, but not all fields can be set. In general, the fields that can be set are Configuration class fields (in ACMS entity tables) and nearly all Manager configuration table fields. See Chapter 9 for a list of all tables and fields.
Object identifier (OID) values are documented in the file MIB_OID.LIS available from the directory ACMS$RM_EXAMPLES. This file presents a list of the ACMS MIB fields and their corresponding SNMP OIDs, as generated from the files MGMTMIB.MY and RFC1155.MY. The MGMTMIB.MY file is found in the ACMS$RM_EXAMPLES. For information about RFC1155, visit the Internet Engineering Task Force (IETF) web site at http://www.ietf.org/.
The information in this list is presented in the form of a table that identifies the name, object identifier, data type, access privilege associated with each ACMS MIB field.
The MIB list is subject to change with each release of ACMS. To obtain the most current information, consult the source document (ACMS$RM_EXAMPLES:MGMTMIB.MY), or regenerate the file, as follows:
|
Security for the SNMP interface is enforced first by the SNMP master agent (not the ACMS MIB). SNMP supports the concept of communities, which are essentially node inclusion lists. Whoever installs and configures the SNMP software package (typically the network manager) sets up SNMP communities.
Nodes that are part of the SNMP community to which the subagent belongs can connect to the master agent; any node that can connect to the master agent can connect and interact with the subagent. All SNMP communities are allowed any combination of read, write, and trap access. Nodes that are not part of the community do not have access to the master agent.
Note that communities work at the node level only. It is not possible to restrict the access of individual user accounts on the node, although it may be possible to restrict access to the SNMP console software on a per-user basis. Note also that node authentication itself is relatively weak and provides no safeguards against masquerades or other forms of network deception.
As a second level of security, the ACMS Remote Manager requires that a special OpenVMS account (ACMS$SNMP) be created for the SNMP interface on nodes on which the Remote Manager runs. The account must be granted OpenVMS rights for read, write, operate access, or update (or some combination of these) to Remote Manager data and functions. This allows ACMS system managers to grant read access, for instance, through the SNMP interface, but to prevent write, operate, or update access. See Section 4.4 for a discussion of how to configure Remote Manager authentication and authorization for the SNMP interface.
| Previous | Next | Contents | Index |