connectSNMP()--Establish Connection with SNMP Agent
Syntax
#include <qtossapi.h> int connectSNMP( char *queue_name, char *lib_name, long int timeout );
Service Program Name: QTOSSAPI
Default Public Authority: *USE
Threadsafe: No
The connectSNMP() function establishes a logical connection between the SNMP subagent and the local (the same system) SNMP agent. The data queue named by the queue_name parameter is used by the SNMP agent as the target data queue in a call to the Send Data Queue (QSNDDTAQ) API when it sends a message to the subagent. Only a single connection is allowed per data queue and library, hence a subagent may have only a single data queue. (Of course, a subagent may have multiple registrations. See mkDPIregister()--Make a DPI Register Packet.)
Authorities
So that the subagent can receive messages from the SNMP agent, the following conditions must be met:
- The library and data queue whose names are passed as a parameter in the
connectSNMP() call must exist prior to the call.
- The SNMP agent job must have write access to the data queue. If you suspect a problem with the data queue, check the job log of the SNMP agent job (QTMSNMP in subsystem QSYSWRK) for TCP4041 messages with reason code 001.
Parameters
- queue_name
- (Input) The name of the data queue (as a null-terminated string) on which
the subagent wants to receive Distributed Protocol Interface (DPI®) packets. The
value must conform to IBM® i rules for data queue names (such as using
uppercase letters and starting with a letter, $, #, @, and so forth).
- lib_name
- (Input) The name of the IBM i library (as a null-terminated string) to
which the data queue belongs. QTEMP is not an allowed value. The value must
conform to IBM i rules for library names (such as using uppercase letters and
starting with a letter, $, #, @, and so forth).
Note that the actual character representation of the specific library name must be used. Special values such as *LIBL and *CURLIB are not allowed.
- timeout
- (Input) The amount of time in seconds that the subagent is willing to wait
for a connection. This field may contain the following values:
0 Unlimited wait > 0 The number of seconds to wait (maximum is 2 147 483 647) Any other values result in an error return code.
Return Value
The return values are defined in the <qtossapi.h> file in the QSYSINC library.
0 | snmpsa_RC_ok
The call was successful. |
-1 | snmpsa_RC_err
An exception occurred. Check the subagent job log for the exception information, correct the condition, and resubmit the subagent job. (This return code is only used when a more specific return code is not available.) |
-2 | snmpsa_RC_noagent
The SNMP agent is not available. |
-3 | snmpsa_RC_mismatch
There is a code-level mismatch between the agent and the subagent. If this occurs, report the problem to the appropriate service organization. |
-4 | snmpsa_RC_timedout
The specified timeout value was exceeded. |
-7 | snmpsa_RC_parmerr
A parameter error occurred. This is more likely caused by errors in the value of a parameter (for example, a value was too large or too small) or by a pointer parameter that has a NULL value and should not. For char* parameters, it may also be caused if the length of the string exceeds some limit. |
-8 | snmpsa_RC_lengtherr
During an attempt to communicate with the agent, a length exception occurred. |
-9 | snmpsa_RC_buffer
An internal buffer was not obtained. See any messages in the job log and correct any errors that are indicated, then retry the operation. |
-10 | snmpsa_RC_duplicate
The agent already has a subagent with this queue and library name. The subagent may continue as usual with the mkDPIopen() and mkDPIregister() functions. If these fail, the subagent should use different library and queue names. |
-13 | snmpsa_RC_alreadyconnected
The subagent is already connected using the same data queue and library names passed on the call. If the SNMP agent still does not forward requests to the subagent properly, use the disconnectSNMP() function, then the connectSNMP() function. |
For more information, see the Simple Network Management Protocol (SNMP) Support manual.
Usage Notes
The connectSNMP() function establishes a logical connection with the SNMP agent that is running on the same system as the subagent. This is normally the first subagent API that a subagent calls.
This API, like all the subagent APIs, checks to ensure that the pointers passed are generally valid for user data, for example, user domain. Such audits occur for all pointer parameters and for all pointers that appear in all C structures that are passed as parameters. If one of these checks fail, a CPF9872 exception is generated. This can occur from all the subagent APIs except debugDPI(), DPI_PACKET_LEN(), and mkDPIAreYouThere().
Related Information
- The <qtossapi.h> file (see Header
Files for UNIX®-Type Functions)
- disconnectSNMP()--End Connection with SNMP
Agent
- mkDPIregister()--Make a DPI Register Packet
Example
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <qtossapi.h> int rc; rc = connectSNMP( "QABCDEFG", "LIBABC", 0 ); if (rc) { /* Handle exception. */ }
API introduced: V3R6