waitDPIpacket()--Wait for a DPI Packet
Syntax
#include <qtossapi.h> int waitDPIpacket( long int timeout, void *dpimsgbuff_p, unsigned long int *length );
Service Program Name: QTOSSAPI
Default Public Authority: *USE
Threadsafe: No
The waitDPIpacket() function waits for a message on the data queue with which the subagent has previously connected (see connectSNMP()--Establish Connection with SNMP Agent). When a Distributed Protocol Interface (DPI®) packet arrives, this function receives the packet and copies it to a subagent buffer.
Authorities
So that the subagent can receive messages from the SNMP agent, the following conditions must be met:
- 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
- timeout
- (Input) The number of seconds that the subagent is willing to wait for a
message (a call to this function will block the subagent until a message is
received or until this timeout is reached).
Possible values have the indicated meaning;
< 0 Unlimited wait 0 No wait. This causes an immediate return if a data queue message is not present. > 0 The number of seconds to wait (maximum is 99999).
- dpimsgbuff_p
- (I/O) A pointer to a buffer that is owned by the subagent. This will
contain the serialized packet from the SNMP agent when snmpsa_RC_ok is
returned. The maximum length of a DPI packet is SNMP_DPI_BUFSIZE, defined in
the <qtossapi.h> file. The buffer will contain the data
queue message itself if that message is not from the SNMP agent, and
waitDPIpacket() will return
snmpsa_RC_nonagentmsg.
- length
- (Output) When snmpsa_RC_ok is returned, the length (in bytes) of the DPI packet received. When snmpsa_RC_nonagentmsg is returned, the length of the data queue message. Otherwise, this value is 0.
Return Value
The return values are defined in the <qtossapi.h> file.
0 | snmpsa_RC_ok
The routine 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
A previous DPI packet was found. The subagent may want to process this packet or call the receiveDPIpacket() function again to get the next packet. |
-4 | snmpsa_RC_timedout
No message was received within the specified timeout. |
-5 | snmpsa_RC_nonagentmsg
A data queue message arrived that is not from the SNMP agent. |
-6 | snmpsa_RC_dqinvalid
The subagent data queue or library is invalid. This refers to the data queue and library used in the connectSNMP() call. |
-7 | snmpsa_RC_parmerr
A parameter error occurred, probably a null pointer. |
-8 | snmpsa_RC_lengtherr
A parameter was an incorrect length. |
-9 | snmpsa_RC_buffer
Check the job log of the subagent for MCH3802. If found, the problem was likely due to agent workload, and the subagent can retry the request. If a different exception is found, see any messages in the job log, correct any errors that are indicated, and then retry the operation. |
-12 | snmpsa_RC_connectfirst
The subagent must connect to the SNMP agent before making this call. |
For more information, see the Simple Network
Management Protocol (SNMP) Support manual.
Usage Notes
The waitDPIpacket() function waits for a message on the data queue that the subagent specified on the connectSNMP() call. When a data queue message is received, the corresponding DPI packet is copied to the specified subagent buffer.
If a data queue message arrives that is not from the SNMP agent, then it is returned in the buffer and the code snmpsa_RC_nonagentmsg is returned.
Related Information
- The <qtossapi.h> file (see Header
Files for UNIX®-Type Functions)
- connectSNMP()--Establish Connection with SNMP
Agent
- pDPIpacket()--Parse a DPI Packet
Example
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <qtossapi.h> #define MAX_LEN 4096 #define waitTIMEOUT 300 unsigned char *pack_p, dpimsgbuff[MAX_LEN]; snmp_dpi_hdr *hdr_p; snmp_dpi_set_packet *set_p; long int num, length; for(;;) { rc = waitDPIpacket( waitTIMEOUT, &dpimsgbuff[0], length ); if (rc<0) { /* Handle exceptions. */ } else { hdr_p = pDPIpacket(pack_p); /* Parse incoming packet. */ /* Assume it's in pack_p. */ if (hdr_p) { /* Analyze packet, assume GET, no error. */ set_p = mkDPIset(snmp_dpi_set_packet_NULL_p, "1.3.6.1.2.3.4.5.", "1.0", SNMP_TYPE_Integer32, sizeof(num), &num); if (set_p) { pack_p = mkDPIresponse(hdr_p, SNMP_ERROR_noError, 0L, set_p); if (pack_p) { /* Send packet to subagent. */ } /*end if*/ } /*end if*/ } /*end if*/ } /*end else*/ } /*end for*/
API introduced: V3R6