receiveDPIpacket()--Receive a DPI Packet from the SNMP Agent

Syntax

 #include <qtossapi.h>

 int   receiveDPIpacket(
           sa_dataq_msg      *dataq_msg_p,  
           void              *dpi_msg_p,
           unsigned long int *length_p );

Service Program Name: QTOSSAPI

Default Public Authority: *USE

Threadsafe: No

The receiveDPIpacket() function obtains a copy of a DPI^® packet sent by the SNMP agent to the subagent, and returns the DPI packet to the caller.

Authorities

Unlike the waitDPIpacket() function, this function does not actually refer to the subagent,s data queue.

Parameters

dataq_msg_p: (Input) A pointer to the data queue message that was sent to the subagent to tell it that a DPI packet is pending. Note that the message must have already been received from the data queue by the subagent and placed in a buffer. This is a pointer to that message in the buffer. Use of this function assumes that the data queue messages are handled directly by the subagent,s own code. See waitDPIpacket() for an alternative.
The sa_dataq_msg structure is defined in the <qtossapi.h> file.
dpi_msg_p: (I/O) A pointer to a buffer set up by the subagent that will contain the DPI serialized packet on successful return from this routine.
length_p: (Output) A pointer to an integer that will contain the length of the DPI packet contained in the subagent,s buffer on successful return.

Return Value

The return values are defined in the <qtossapi.h> file.

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 A previous DPI packet was found. The subagent may want to process this packet or call receiveDPIpacket() again to get the next packet. See any messages in the job log and correct any errors that are indicated, then retry the operation.
-5	snmpsa_RC_nonagentmsg The data queue message is not from the SNMP agent. (There is no DPI packet pending.)
-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 Link to PDF manual.

Usage Notes

The receiveDPIpacket() function obtains a copy of a DPI packet sent to the subagent. The copy is placed in a buffer owned by the subagent.

Use of this function by a subagent requires that the subagent programmer must wait for and receive the prompting message on the subagent,s data queue. An alternative is to use the waitDPIpacket() function, which handles the data queue for the subagent and also receives the DPI packet.

Related Information

The <qtossapi.h> file (see Header Files for UNIX^®-Type Functions)
waitDPIpacket()--Wait for 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_MSG_SIZE       4096
  char      dpibuff[MAX_MSG_SIZE],
            dataqbuff[80];
  int       rc, len;

  /* Wait for message on data queue.  When it arrives...        */
  QRCVDTAQ( ... )
  /* Handle exceptions. */

  rc = receiveDPIpacket( &dataqbuff[0],
                         &dpibuff[0], &len );
  if (rc) {
     /* Handle exceptions. */
  }

API introduced: V3R6

[ Back to top | UNIX-Type APIs | APIs by category ]