Network management is the process of planning, organizing, and controlling a communications-oriented system. It provides you with the capability to manage one or more nodes from another node.
The network management APIs are grouped as follows:
This section provides a brief description of each category of network management APIs.
APPN topology information APIs allow an application to obtain information about the current APPN topology, and to register and deregister for information about ongoing updates to the topology. Current topology information is an option provided by the Register for APPN Topology Information (QNMRGTI) API. When this option is requested, the current APPN topology is reported to a user space specified by the application running the API. This API also provides topology update options that allow the application to register a queue to receive information about specific types of APPN topology updates. Topology updates are reported asynchronously to the specified queue as they occur in the network.
A queue remains registered for topology updates until one of the following occurs:
One application in each job on the system may register one queue for topology updates. Multiple queues may not be registered for topology updates within the same job.
The specific types of topology updates that an application may register to receive are:
The queue and user space objects specified on the APPN topology information APIs must be managed entirely by the application; for example, the application must create, delete and maintain the objects itself, using the APIs for those objects. The application is responsible for any error handling should these objects become damaged or deleted.
If an error occurs while reporting the current topology to the specified user space, an error is returned through the API. If an error occurs while enqueuing ongoing topology updates to a registered queue, the resulting error messages are sent to the job log, followed by diagnostic message CPD91C9, and the queue is automatically deregistered by the system. If automatic handling of this diagnostic error message is necessary, an application could periodically scan the job log for this message using the List Job Log (QMHLJOBL) API and take appropriate action.
After the current topology has been requested using the QNMRGTI API, the data returned in the user space may be retrieved using the Retrieve User Space (QUSRTVUS) API. If a data queue is registered for topology updates using the QNMRGTI API, topology update records may be retrieved out of a data queue using the Receive Data Queue (QRCVDTAQ) API. If a user queue is registered (rather than a data queue), the application must use the dequeue (DEQ) MI instruction to retrieve queue records. The first 10 characters of each queue entry contains the value *APPNTOP so that the application can distinguish these records from others on the queue. This allows a queue to be used for multiple purposes.
Topology updates can be separated into two classes:
APPN network topology identifies the following in an APPN subnetwork:
| An APPN subnetwork consists of nodes having a common network ID and the links connecting those nodes. |
APPN network nodes exchange network topology updates in a subnetwork through topology database updates (TDUs). Therefore, only network nodes can report network topology updates. See System Network Architecture Formats for details about TDUs.
The local topology for an APPN node consists of the following:
Both end nodes and network nodes can report local topology updates.
Network nodes in separate subnetworks may be connected by an intersubnetwork transmission group, a group of links between directly attached nodes of 2 or more subnetworks appearing as a single logical link for routing messages. In this case, the network node at each end point of the transmission group is present only in the partner network node's local topology, not in its network topology. For example, consider two network nodes with different network IDs in separate subnetworks:
Systems Network Architecture (SNA) Management Services Transport (SNA/MS Transport) functions are used to support the sending and receiving of management services data between systems in an SNA network. The network can include AS/400 systems, Operating System/2 and NetView licensed programs, and other platforms that support the SNA/Management Services architecture.
The SNA/Management Services functions provided on the AS/400 system include:
The APIs allow a network management application running on one system to send data to and receive data from a network management application running on another system in an APPN network. The APIs are a callable interface that allow the application to be notified about asynchronous events, such as incoming data, by way of a notification placed on a data queue.
Some examples of IBM applications that use SNA/Management Services Transport APIs are:
In large networks, the number of sessions needed to support the various network management applications could become burdensome without session concentration. SNA/Management Services Transport APIs reduce the number of SNA LU 6.2 sessions that would normally be used to transmit data. This support multiplexes or transmits all of the network management data from all the applications in a network node domain (network node and attached end nodes) on a single session to applications in another domain.
This means that data transmitted from an end node is always sent to its network node server first. Then, the SNA/Management Services Transport support on the network node server routes the data to its proper destination.
SNA/Management Services is used by two types of applications: a source application and a target application. A source application sends requests to and receives replies from a target application. Similarly, a target application receives requests from and sends replies to a source application.
For a target application to receive requests from a source application, the target application must perform the following operations:
When the request arrives, the target application receives an entry from the data queue using the QRCVDTAQ API. The target application then uses the request identifier in the entry to receive the data (call the Receive Data (QNMRCVDT) API). The data queue entry has the following format.
| Offset | Type | Value | Field | |
|---|---|---|---|---|
| Dec | Hex | |||
| 0 | 0 | CHAR(10) | *SNAMST | Entry type |
| 10 | A | CHAR(2) | 01 | Incoming data |
|
|
|
| 02 | Send complete |
| 12 | C | BINARY(4) |
| Handle |
| 16 | 10 | CHAR(53) |
| Request identifier |
| 69 | 45 | CHAR(11) |
| Reserved |
This topic describes the fields returned in further detail. The fields are listed in alphabetical order.
Entry type. This entry was created by SNA/Management Services Transport.
Handle. This value specifies the handle of the application associated with the data queue.
Incoming data. The incoming data has arrived and that the Receive Data (QNMRCVDT) API should be called.
Request identifier. Identifies incoming or transmitted data. This field is used when calling Receive Data (QNMRCVDT) and Receive Operation Completion (QNMRCVOC).
Reserved. An ignored field.
Send complete. A previous send operation has completed and that the Receive Operation Completion (QNMRCVOC) API should be called.
Then, depending on whether or not the request requires a reply, the target application may need to send a reply to the source application. A reply is sent using the Send Reply (QNMSNDRP) API.
A single request may require more than one reply. If a request is not recognized, a single error message may be sent instead of a reply using the Send Error (QNMSNDER) API.
Also, the source application must start the application (call the QNMSTRAP API), but the source does not need to create a data queue or register itself with SNA/Management Services Transport support. The source application can send a request to the target application, using the Send Request (QNMSNDRQ) API. The QNMSNDRQ API returns a request identifier that is used to receive any associated replies.
The source application receives any expected replies (call the QNMRCVDT API) with the request identifier parameter specified as the request identifier returned when the Send Request (QNMSNDRQ) API was called.
Both the target and the source applications use the End Application (QNMENDAP) API to end the management services transport support. The target application may optionally use the Deregister Application (QNMDRGAP) API before ending. However, the QNMENDAP API automatically performs a deregister operation.
The example in Figure 1 shows how these SNA/Management Services Transport APIs work together.
Figure 1. Applications Using SNA/Management Services Transport APIs
The types of data handled by SNA/Management Services may be:
The list correlates to the numbers on the left in Figure 2, which shows the flow of data requests and replies depending on the parameters specified.
Figure 2. Data Types Handled by SNA/Management Services Transport APIs
Notes:
SNA/Management Services Transport performs all routing based on the network ID, control point name (or a logical unit name may be used), and application name. Applications must be registered with SNA/Management Services to receive unsolicited requests.
Communications from a network node to an end node is normally performed through the end node's network node server. In the network node server, SNA/Management Services Transport provides intermediate routing functions between the end node and the network node. This is separate from the intermediate routing provided by APPN network node services.
By default, data sent using the SNA/Management Services Transport APIs uses sessions associated with system mode names CPSVCMG and SNASVCMG. CPSVCMG sessions are used between an end node and its network node server. SNASVCMG sessions are used between network nodes.
When data is sent from an end node to a network node that is not its network node server, its network node server performs intermediate routing between the CPSVCMG session and the SNASVCMG session.
Other sessions can be established by specifying a different mode name with the Change Mode Name (QNMCHGMN) API. When you change the mode name, APPN network node services performs the intermediate routing function rather than SNA/Management Services Transport. This is known as direct routing to SNA/Management Services Transport.
The alert APIs let your application create alerts, notify the OS/400 alert manager of alerts that need to be handled, and allow you to retrieve alerts and alert data. The generate and send APIs differ from ordinary AS/400 alert processing in that they let your application create an alert at any time without sending an alertable message to an alertable message queue. (An alertable message queue is a message queue that has been created or changed with the allow alerts (ALWALR) parameter specified as yes.) The retrieve API allows your application, in conjunction with alert filtering, to perform user-defined actions based on the contents of the alert.
For more information on creating and sending OS/400 alerts, see the manual Alerts Support. For details about the contents of alerts built by the AS/400 system, see the SNA Formats manual.
A node list contains a list of systems identified by a remote location name and an address type. Nodes with an SNA address type are identified by a network ID and a control point name. Nodes with an internet protocol (IP) type are identified by a host name or an internet address. The List Node List Entries (QFVLSTNL) API returns, in a user space, a list of the nodes contained in the specified node list object.
A filter is a function you can use to assign events into groups and to specify actions to take for each group. The registered filter APIs allow a product to register a filter with the operating system. The product can receive notification of events recorded in a data queue by using the Send to Data Queue (SNDDTAQ) action of the Work with Filter Action Entry (WRKFTRACNE) command.
A user filter is the filter defined by the network attributes for alert filtering and by the system value for problem log filtering. A user filter and a registered filter differ in their function and their notification record. There can only be one user filter active at one time for each type of filter, but there can be multiple registered filters active at one time. All actions are active for a user filter, but only the SNDDTAQ action is active for a registered filter.
A product can use registered filter APIs for the following purposes:
The event notification record for a registered filter differs from notification records for other types of filters. The registered notification contains a common header for all events, as well as specific information based on the type of event. The common header includes the name of the notification, a function type, a format, the filter name and library, the group name, and a timestamp. The specific information for the problem log includes the problem ID, the last event logged, and the timestamp for the last event.
The change request management APIs add, remove, and list activities and retrieve change request descriptions.
| Top | APIs by category |
| [Information Center Home Page | Feedback ] | [Legal | AS/400 Glossary] |