Simple Network Management Protocol (SNMP) Subagent APIs
The SNMP subagent APIs are:
- connectSNMP() (Establish connection with SNMP agent) establishes a logical connection between the SNMP subagent and the local (the same system) SNMP agent.
- debugDPI() (Set DPI packet trace) sets the level of the Distributed Protocol Interface (DPI) packet trace.
- disconnectSNMP() (End connection with SNMP agent) ends the logical connection between the SNMP subagent and the SNMP agent.
- DPI_PACKET_LEN() (Get length of DPI packet) returns the length (number of bytes) of a Distributed Protocol Interface (DPI) packet.
- fDPIparse() (Free storage from DPI packet parse) frees storage that was previously allocated by a call to pDPIpacket() to store the DPI packet.
- fDPIset() (Free storage from DPI set packet) frees storage that was previously allocated for snmp_dpi_set_packet structures.
- mkDPIAreYouThere() (Make a DPI AreYouThere packet) makes a DPI AreYouThere packet and returns a pointer to the packet.
- mkDPIclose() (Make a DPI close packet) makes a DPI close packet and returns a pointer to the packet.
- mkDPIopen() (Make a DPI open packet) makes a Distributed Protocol Interface (DPI) open packet and returns a pointer to the packet.
- mkDPIregister() (Make a DPI register packet) makes a Distributed Protocol Interface (DPI) register packet and returns a pointer to the packet.
- mkDPIresponse() (Make a DPI response packet) makes a DPI response packet and returns a pointer to the packet.
- mkDPIset() (Make a DPI set packet) makes a DPI set structure and adds it to a chained list of set structures if previous calls have been made.
- mkDPItrap() (Make a DPI trap packet) makes a DPI trap packet and returns a pointer to the packet.
- mkDPIunregister() (Make a DPI unregister packet) makes a DPI unregister packet and returns a pointer to the packet.
- pDPIpacket() (Parse a DPI packet) parses a serialized Distributed Protocol Interface (DPI) packet to make it available for processing by the subagent.
- receiveDPIpacket() (Receive a DPI packet from the SNMP agent) obtains a copy of a DPI packet sent by the SNMP agent to the subagent, and returns the DPI packet to the caller.
- sendDPIpacket() (Send a DPI packet to the SNMP agent) sends a copy of a Distributed Protocol Interface (DPI) packet to the SNMP agent (on the same system as the subagent).
- waitDPIpacket() (Wait for a DPI packet) waits for a message on the data queue with which the subagent has previously connected (see connectSNMP()--Establish Connection with SNMP Agent).
Note: These functions use header (include) files from the library QSYSINC, which is optionally installable. Make sure QSYSINC is installed on your system before using any of the functions. All of the SNMP subagent APIs use header file qtossapi.h. You can see this source in source file H, member name QTOSSAPI, in the QSYSINC library.
The Simple Network Management Protocol (SNMP) subagent APIs can be used to dynamically extend the management information base (MIB) that the system SNMP agent is aware of. The MIB is extended, without any change to the SNMP agent itself, while the system is running. Dynamically added MIB subtrees (as defined and supported by a program known as a subagent) provide this capability. You may now extend the remote and automated system management capabilities of the system within the SNMP framework. So, for example, you could define an SNMP MIB group for your RPG and SQL application, and then use SNMP protocol data units (PDUs), such as get and set, to determine status information or to make changes in control variables.
The Distributed Protocol Interface (DPI®) packet is used throughout this information. The DPI is an extension to SNMP agents that permit users to dynamically add, delete, or replace management variables in the local MIB without requiring recompilation of the SNMP agent.
The diagram below shows typical DPI API call sequences that are used to accomplish the SNMP subagent functions that are listed.
| (A) | Subagent initiation |
| (B) | Subagent registration (loop for multiple subtrees) |
| (C) | Normal processing loop for a subagent, starting with a wait for a (get, getnext, set...) packet from the SNMP agent (other may be an unregister or close packet) |
| (D) | A common call sequence that might be consolidated |
| (E) | Subagent initiated trap |
| (F) | Subagent termination
A loop around mkDPIset() represents building a packet with multiple varbinds. |
DPI API Call Sequences--Example
