A - Man Page Summary for Writers of Manager Applications

A.1 Setting the MANPATH Variable

A.1.1 MANPATH Setting for Solaris 2.4

For a C-shell, in your $HOME/.cshrc file enter:

setenv MANPATH ${MANPATH}:/opt/SUNWconn/man

For a Bourne or Korn shell, in your $HOME/.profile file enter:

set MANPATH=${MANPATH}:/opt/SUNWconn/man export MANPATH

A.1.2 MANPATH Setting for Solaris 1.1.1

For a C-shell, in your $HOME/.cshrc file enter:

setenv MANPATH ${MANPATH}:/usr/man

For a Bourne or Korn shell, in your $HOME/.profile file enter:

set MANPATH=${MANPATH}:/usr/man export MANPATH

A.2 Utilities

snm_cmd

The command-line manager for agents. It provides a way to send requests to agents without having to run the Console or write dedicated test programs.

snm_kill

Stop one or more agent requests. This command allows you to stop requests from other than where they were started.

snm_parser

An example application for parsing schema files. This program is provided in source form to allow you to easily build applications that can read schema files.

A.3 Manager Services Library Routines

netmgt_alloc_manager_id

Allocates a unique ID to the calling manager application. This ID is the inode number of a temporary file in the product directory.

netmgt_dbg

Three macros--for each of three debug levels--used for print tracing information. The arguments are identical to those of printf.

netmgt_fetch_data

Gets data statistics from a data report and places them into a local buffer that you specify. When a rendezvous receives a data report, the first call to this function gets the first data statistic in the report. Subsequent calls get successive statistics.

netmgt_fetch_error

Copies the relevant portions of the global netmgt_error structure into a user-specified buffer.

netmgt_fetch_event

Gets event statistics out of an event report and places them into a local buffer. When a rendezvous receives a data report, the first call to this function gets the first data statistic in the report. Subsequent calls get successive statistics.

netmgt_fetch_msginfo

Obtains additional message information from a data or event report and places it into a local buffer.

netmgt_free_manager_id

Deallocates a manager ID previously allocated by a call to netmgt_alloc_manager_id().

netmgt_get_manager_id

Returns the value of the manager ID field in data, event, set, trap, and error reports. This function may only be called by applications that receive such reports.

netmgt_kill_request

Terminate a specific request on a specific host.

netmgt_kill_request2

Terminate all requests on a specific host started by a specific manager application.

netmgt_oid2string

Converts an SNMP object identifier to a text string.

netmgt_register_callback

Establishes a rendezvous for receiving data or event reports by registering a transient RPC callback function.

netmgt_register_rendez

Instructs the event dispatcher on a specific host to start sending event reports from a specified agent to a specified rendezvous.

netmgt_request_agent_ID

Requests identification from an agent.

netmgt_request_data

Sends a request to an agent for a specific group's attribute values. The caller must have previously called netmgt_set_instance(3n) to define the system, group, and optional key of the request. If any agent-specific options are to be set, the caller must have previously called netmgt_set_argument(3n).

netmgt_request_deferred

Get any available deferred data reports (that is, data reports for which a manager application has previously requested an agent to defer sending).

netmgt_request_events

Sends a request to an agent to watch for interesting events related to specific attributes.

netmgt_request_set

Sends a request to an agent to set the values of one or more group or table attributes. The return value is a boolean value (true or false).

netmgt_request_set2

Identical to netmgt_request_set except that the return value for this function is the timestamp of the request, if successful, Otherwise the return is null.

netmgt_request_set

netmgt_restore_argument

Sets an argument from the contents of the buffer pointed to by `argument'.

netmgt_restore_request

Sets the current request state from the contents of the buffer pointed to by 'request_info'.

netmgt_restore_threshold

Sets a threshold from the contents of the buffer pointed to by 'threshold'.

netmgt_save_argument

Man page also includes netmgt_restore_argument. Copies information about an optional argument into the buffer pointed to by the sole argument to the function. The "restore" function sets an argument from the contents of the buffer pointed to by the sole argument to netmgt_restore_argument .

netmgt_save_attribute

This routine is used primarily by the agent programs. When a data request is sent to an agent, the agent program should invoke this routine to save all the attributes requested and accordingly fetch the data from the managed device. The number of attributes requested is available in the request info structure; this routine should be called accordingly. If no attributes are specified then all the attributes in a given group are retrieved.

netmgt_save_request

Man page also includes netmgt_restore_request. Copies information about the current request state into the buffer pointed to by the sole argument to the function. The "restore" function sets the current request state from the contents of the buffer pointed to by the sole argument.

netmgt_save_threshold

Man page also includes netmgt_restore_threshold. Copies information about an event threshold into the buffer pointed to by the sole argument to the function. The "restore" function sets a threshold from the contents of the buffer pointed to by the sole argument to netmgt_restore_threshold .

netmgt_set_argument

Specifies optional request arguments to be sent to an agent. These optional arguments are agent-specific, for directing the agent to perform actions not accounted for by the standard request mechanisms.

netmgt_set_attribute

Allows the management applications, such as the console, to specify the set of attributes to be retrieved in a data report request.

While requesting data requests this routine must be called after netmgt_set_instance() and netmgt_set_argument(), but before the netmgt_request_data() call. This routine should be called separately for each and every attribute to be retrieved in a data request. If this routine is not invoked, then the behaviour is same as in earlier product releases, which is to retrieve all the attributes in any given group.

netmgt_set_debug

Sets one of four debugging levels for application execution tracing.

netmgt_set_instance

Specifies the parameters--including the system name, attribute group, and optional key into a table of attributes--an agent should use when making a request.

netmgt_set_manager_id

Covers four functions, to allocate, free, set, and get a manager ID. A manager ID is associated with an individual manager application. It is used to distinguish among requests started by multiple manager applications running on the same machine.

netmgt_set_threshold

Sets the event report threshold for an attribute value.

netmgt_set_value

Specifies a set request argument to be sent to an agent. This function is called once for each attribute to be set.

netmgt_sperror

Returns the error description string associated with the last error contained in the global variable netmgt_error.

netmgt_unregister_callback

Unregisters a specified transient RPC callback function.

netmgt_unregister_rendez

Asks the event dispatcher on a specified host to stop sending event reports of a specified priority from agents of a specified RPC program number to the rendezvous process with a specified RPC program and version number on a specified host.

A.4 Database Library Routines

snm_error

An external variable containing the error reason for the last error. It should not be used if the return code of the snmdb routine is true.

snmdb_add

Adds a new element into the database.

snmdb_add_agent

Adds an agent record for the element. You add an agent record in the element buffer by specifying the name of the agent and, if the agent is a proxy, the name of the system providing the proxy function.

snmdb_add_alias

Adds an alias record for the element. The name of element used at creation time is its primary name. There may be one or more secondary names added later for the element by adding alias records. Both primary and secondary names should be unique in the elements name space.

snmdb_add_connection

Connections are described in the connect record in the element buffer. This function adds a connect record into the buffer, specifying the target that the element is connected to.

snmdb_add_to_view

The view in which the element exists is described in the element's membership record. This function adds a membership record with the specified view name into the element buffer.

snmdb_console_load

Causes the Console to load a specified ASCII management database file.

snmdb_console_reload

Causes the Console to reinitialize the runtime database and load the specific server.

snmdb_console_save_components

Causes the SNM Console to save all instances in its runtime database to a specified ASCII management database file.

snmdb_delete

Deletes an existing element from the database.

snmdb_delete_agent

Deletes an agent record from the element buffer.

snmdb_delete_alias

Deletes an alias record for the element.

snmdb_delete_color

The color of an element is described in the glyphColor record in the element buffer. This function deletes the glyphColor record from the buffer.

snmdb_delete_connection

Connections are described in the connect record in the element buffer. This function looks through all of the connect records in the buffer and deletes the connection between the element and the target that the element is connected to.

snmdb_delete_from_view

The view in which the element exists is described in the element's membership record. This function deletes a membership record with the specified view name from the element buffer.

snmdb_enumerate_agents

Agents and proxy agents are described in the agent record in the element buffer. This function enumerates the agent records in the buffer and returns a pointer to the list of all agent names.

snmdb_enumerate_aliases

An element may be identified by its secondary names specified in the alias records in the element buffer. This function enumerates the alias records in the buffer and returns a pointer pointing to the list of all alias names.

snmdb_enumerate_connections

Connections are described in the connect record in the element buffer. This function enumerates the connect records in the buffer and returns a pointer to the list of all the names to which the element is connected.

snmdb_enumerate_elements

Enumerates all the elements in a specified view or in all views if no view is specified.

snmdb_enumerate_views

The view in which the element exists is described in the element's membership record. This function enumerates the membership records in the element buffer and returns a pointer to the list of all view names in which the element exists.

snmdb_free_enumeration_handle

Frees the storage allocated previously for enumerating element names.

snmdb_free_list

Frees the storage allocated previously for enumerating agents, views, or connections.

snmdb_get_agent

Retrieves an agent record for a specified agent, indicating whether the agent is a proxy and, if it is, the name of the system that provides the proxy function.

snmdb_get_color

Determines the color value in RGB numbers of the element loaded in the buffer. The colors are contained in the glyphColor record in the buffer.

snmdb_get_element_glyph

Returns the glyph/icon file name for a particular type of element.

snmdb_get_element_type

Returns the type of an element loaded in the internal buffer.

snmdb_get_next_element

Gets the next element in an enumerated list that is generated by snmdb_enumerate_elements .

snmdb_get_property

Gets the value and data type of a particular property of an element that has been read into the internal buffer.

snmdb_get_view

The membership records in the element buffer describe the x and y coordinate values of the element in the views and whether the glyph of the element is stacked on top of another glyph (z value). This function retrieves the x and y coordinates in the membership record that describe the position of the element in a specified view. It also retrieves the z value, used when glyphs are stacked on top of one another.

snmdb_init_buffer

Before adding a new element to the database, you must call this function to initialize the buffer for the element and to set the name and type for the element. See this man page for other function calls needed to add an element into the database.

snmdb_lock

Locks the database so that entries can be changed. Returns a boolean.

snmdb_open

Called before any database operations. Opens the database and performs necessary setup work. Returns a boolean.

snmdb_read

Reads an existing element from the database into the specified internal buffer. This is a pre-requirement for retrieving or updating any properties of a particular element.

snmdb_save_element

Writes the contents in the element buffer into a specified ASCII file, which duplicates the Console's save-file.

snmdb_set_color

Changes the color value in RGB numbers of the element in the buffer. The colors are contained in the glyphColor record in the buffer. If the glyphColor record is not already defined in the buffer, a new one is created.

snmdb_set_property

Sets the value of a particular property of an element. Called in a sequence with other functions, described in this man page, to initialize, read, and update an element.

snmdb_unlock

Unlocks the database and notifies the Console to update its views.

snmdb_update

Writes an updated element back into the database. Called as the last function in the sequence described in the snmdb_set_property man page.

Copyright 1996 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA 94043-1100 USA. All Rights Reserved