SNA/Management Services Transport APIs

The SNA/Management Services Transport APIs are:

• Change Mode Name (QNMCHGMN) sets the APPC mode name used when sending requests.
• Deregister Application (QNMDRGAP) removes the registration of the application name associated with a handle.
• End Application (QNMENDAP) ends support for the application associated with the handle.
• Receive Data (QNMRCVDT) receives a particular request, reply, or error message.
• Receive Operation Completion (QNMRCVOC) receives an operation completion, which allows an application to determine if a send operation completed successfully.
• Register Application (QNMREGAP) registers the application name specified in the previous start application operation so that it may receive unsolicited requests.
• Retrieve Mode Name (QNMRTVMN) retrieves the APPC mode name currently being used for the purpose of sending requests.
• Send Error (QNMSNDER) sends an SNA/Management Services error message to the remote application.
• Send Reply (QNMSNDRP) sends a reply to a request that was received from a source application.
• Send Request (QNMSNDRQ) sends a request to a remote application.
• Start Application (QNMSTRAP) starts support for a network management application.

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 System i™ platforms, 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 System i product include:

• The transport of network management data in APPN networks
• The maintenance of node relationships for network management

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:

• Alerts
• Problem reporting
• Remote problem analysis
• Program temporary fix (PTF) ordering

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.

Using the SNA/Management Services Transport APIs

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:

1. Create a data queue, using the Create Data Queue (CRTDTAQ) command, to allow SNA/Management Services Transport support to indicate incoming data (the MAXLEN parameter must be 80 or greater and the SEQ parameter must be *FIFO).
2. Start an application specifying the data queue just created, using the Start Application (QNMSTRAP) API. The application can then receive a handle, which will be used by the application on all following API calls. The handle is an identifier that represents the application being worked on and is unique within a job.
3. Register an application, using the Register Application (QNMREGAP) API. This notifies SNA/Management Services Transport support that the application is able to receive requests from source applications.
4. Wait for a request to arrive using the Receive Data Queue (QRCVDTAQ) API. See Receive Data Queue (QRCVDTAQ) API for more information.

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.

Entry Format

Field Descriptions

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 following example shows how these SNA/Management Services Transport APIs work together.

Applications Using SNA/Management Services Transport APIs

Data

The types of data handled by SNA/Management Services may be:

1. A request with a single reply expected (for example, a request for current information.
2. A request without a reply (for example, an alert)
3. A request with multiple replies expected
4. An unrecognized request returning an error message

The list correlates to the numbers on the left in the following example, which shows the flow of data requests and replies depending on the parameters specified.

Data Types Handled by SNA/Management Services Transport APIs

Notes:

1. Arrival of requests is not guaranteed unless a reply is requested. The reply acts as a form of acknowledgment.
2. The maximum amount of application data in a single request or reply is 31 739 bytes.

Routing

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.

[ Back to top | Network Management APIs | APIs by category ]