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 "SNMP Subagent Problem Determination" in the Simple Network Management Protocol Link to PDF book.


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


Example

See Code disclaimer information for information pertaining to code examples.

  #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
Top | UNIX-Type APIs | APIs by category