| Previous | Contents | Index |
If the call completed successfully, the code drops into a FOR loop and starts printing the data. For this particular call, the client prints all the records the very first time the RPC is called; on subsequent calls, the first record is a duplicate of the last one from the previous call and is not printed.
After printing a record, the key data is saved to be used again on a subsequent call. Remember that only max_rpc_return_recs is returned in each call to the acmsmgmt_list_log_data_1 procedure. There may be more log records than can be sent at once. It is the responsibility of the client to initialize the call properly to get the next set of records.
Once all the returned records have been returned, the code will call
the acmsmgmt_list_log_data_1 procedure again if the status code from
the call was not MGMT_NOMORE_DATA. In this way, all the records are
retrieved.
5.6 Set Procedures
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 5-4 shows, a separate set procedure is available for each entity and table.
| Procedure | Description |
|---|---|
| acmsmgmt_set_acc_1 | No keys; only 1 ACC per node. |
| acmsmgmt_set_coll_1 | Key value is entity, ID, and class. |
| acmsmgmt_set_exc_1 | Key value is application name. |
| acmsmgmt_set_interface_1 | Key value is interface name. |
| acmsmgmt_set_param_1 | No keys; only one row in the parameter table. |
| acmsmgmt_set_qti_1 | 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_1 | 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 5.7 and Section 5.8) 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 7 for details about each call.
5.6.1 Set Example
The following example code shows how a client program calls the acmsmgmt_set_param_1 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 5.3.
int set_param_data(int client_id,CLIENT *cl)
{
int x = 0;
int y = 0;
static param_config_rec set_struct;
static param_status_rec *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_1(&set_struct,cl);
if (ret_struct->status != MGMT_SUCCESS) {
if (ret_struct->status != MGMT_WARN) {
printf("\nCall to modify parameters failed");
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");
return(MGMT_FAIL);
}
printf("\n Call to update parameters successful");
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.
5.7 Delete Procedures
Delete procedures are available for the Collection and Trap tables. Delete procedures allow you to remove rows from the corresponding table. As Table 5-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 7 for details about each call.
| Procedure | Description |
|---|---|
| acmsmgmt_delete_collection_1 | Key value is entity, ID, and class. |
| 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 5.3.
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 != MGMT_SUCCESS) {
printf("\nCall to delete collection failed with status",*status);
return(0);
}
else
printf("\nCall to delete collection was executed");
return(1);
}
|
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.
5.8 Add Procedures
Add procedures are available for the Collection and Trap tables. Add procedures provide the ability to add rows to the corresponding table. As shown in Table 5-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 7 for details about each call.
| Procedure | Description |
|---|---|
| acmsmgmt_add_collection_1 | Key value is entity, ID, and class. |
| 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_1 procedure to add a collection row.
This example assumes client initialization has been performed as described in Section 5.3.
int add_coll_data(int client_id,CLIENT *cl)
{
static char c_id_all[2] = "*";
static char ent_name[MGMT_S_ENTITY_NAME];
static coll_config_rec set_struct;
static struct coll_status_rec *status_rec;
set_struct.client_id = client_id;
set_struct.coll.entity_type = MGMT_ACC;
set_struct.coll.entity_name = c_id_all;
set_struct.coll.collection_class = MGMT_CLASS_ALL;
set_struct.coll.collection_state = MGMT_STATE_ENABLED;
status_rec = acmsmgmt_add_collection_1(&set_struct,cl);
if (!status_rec) {
printf("\n Call to add collection record failed");
return(0);
}
if (status_rec->status == MGMT_WARN) {
printf("\nThe following fields are invalid: ");
if (status_rec->coll_status_rec_u.data_warn.entity_type == MGMT_FAIL)
printf("\n Record not found");
if (status_rec->coll_status_rec_u.data_warn.collection_class == MGMT_FAIL)
printf("\n collection_class");
if (status_rec->coll_status_rec_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_u.rc);
return(0);
}
else {
printf("\nCall to add collection was executed");
}
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.
5.9 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 7.
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 5.5.1.)
All calls are synchronous.
See Chapter 7 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_tsc_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_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 5.3.
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 General failure calling Remote Manager to start ACMS system");
return(0);
}
if (ret_struct->status != MGMT_SUCCESS) {
if (ret_struct->status != MGMT_WARN) {
printf("\nCall to start ACMS system failed");
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);
return(0);
}
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);
}
return(1);
}
|
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 5.5.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.
6.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 6-1 illustrates the SNMP interface with the ACMS Remote Manager.
Figure 6-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 8 for a list of all tables and fields. Object
identifier (OID) values are documented in Appendix C. In addition,
ACMS provides the MIB definition in source format in the
ACMS$RM_EXAMPLES directory (MGMTMIB.MY).
6.2 SNMP Security
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, or operate access (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 or operate access. See Section 3.4
for a discussion of how to configure Remote Manager authentication and
authorization for the SNMP interface.
6.3 Initializing the SNMP Interface
In order for SNMP consoles to communicate with the ACMS Remote Manager through SNMP, the Remote Manager SNMP interface must have been started. The SNMP interface runs as a separate thread in the Remote Manager and can be started or stopped at any time without restarting the Remote Manager.
The SNMP interface is started using the SET INTERFACE command. The current state of the interface can be determined using the SHOW INTERFACE command. Refer to Section 3.5 for more information about using ACMSCFG and ACMSMGR to start and stop interfaces.
During startup, the SNMP interface first performs some housekeeping tasks and then attempts to register with the SNMP master agent.
In order for the SNMP interface to initialize successfully, the following conditions must be met:
If any of the initialization tasks fail, or if registration fails, the SNMP interface writes error messages to the Remote Manager log and the thread exits. In this case, users should check the Remote Manager log for messages, correct the problem, and restart the interface.
During initialization, the Remote Manager establishes a timeout that the master agent will use when communicating with it. The timeout is based on the value of the Remote Manager parameter SNMP_AGENT_TIME_OUT.
If initialization is successful, the SNMP interface thread waits for incoming SNMP requests. The wait times out periodically (based on the Remote Manager parameters SNMP_SEL_TIME_OUT and SNMP_ARE_YOU_THERE stored in the Parameter table), and checks to make sure the SNMP master agent is still running by sending an "are you there" message to the master agent. If the master agent responds, the Remote Manager continues to wait for incoming messages. If the master agent does not respond, the SNMP interface thread attempts to restart the connection. If the restart fails, the SNMP thread exits.
| Previous | Next | Contents | Index |