connectSNMP()--Establish Connection with SNMP Agent

 #include <qtossapi.h>

 int               connectSNMP(
           char         *queue_name,   
           char         *lib_name,
           long int     timeout );

The connectSNMP() function establishes a logical connection between the SNMP subagent and the local (the same iSeries server) 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 i5/OS 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 i5/OS library (as a null-terminated string) to which the data queue belongs. QTEMP is not an allowed value. The value must conform to i5/OS 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.

For more information, see "SNMP Subagent Problem Determination" in the Simple Network Management Protocol (SNMP) Support book.

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

See Code disclaimer information for information pertaining to code examples.

  #include <qtossapi.h>
  int      rc;

  rc = connectSNMP( "QABCDEFG", "LIBABC", 0 );
  if (rc) {
     /* Handle exception. */
  }