mkDPIregister()--Make a DPI Register Packet

 #include <qtossapi.h>

 unsigned char     *mkDPIregister(
     unsigned short     timeout,
     long int           priority,
     char               *group_p,
     char               bulk_select);   

The mkDPIregister() function makes a Distributed Protocol Interface (DPI) register packet and returns a pointer to the packet.

Authorities and Locks

None.

Parameters

timeout

(Input) The requested timeout in seconds. An agent often has a limit for this value, and it will use that limit if this value is larger. The value zero has special meaning in the sense that it tells the agent to use the timeout value that was specified in the DPI OPEN packet.

priority

(Input) The requested priority, relative to other DPI subagents. This field may contain any of these values:

-1	The best available priority.
0	A better priority than the highest priority currently registered. Use this value to obtain the SNMP DPI version 1 behavior.
nnn	Any other positive value. You will receive that priority if available; otherwise, the next best priority that is available.

group_p

(Input) A pointer to a NULL-terminated character string that represents the subtree to be registered. This group ID must have a trailing dot.

bulk_select

(Input) Whether you want the agent to pass GETBULK on to the subagent or to map them into multiple GETNEXT requests. The possible value follows:

DPI_BULK_NO

Do not pass any GETBULK requests, but instead map a GETBULK request into multiple GETNEXT requests.

Return Value

Be aware that the static buffer for the DPI packet is shared by other mkDPIxxxx() functions that create a serialized DPI packet.

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

Usage Notes

The mkDPIregister() function creates a serialized DPI REGISTER packet that can then be sent to the SNMP agent.

The SNMP agent will send a DPI response packet back to the subagent with a code that can be used to determine if the register request was successful. This will be one of the SNMP_ERROR_DPI_* return codes found in <qtossapi.h>. Following receipt of this response packet, the subagent will need to call the pDPIpacket() to parse the incoming DPI packet and to check the response packet error_code. Then, fDPIparse() would normally be called to free the parsed DPI packet.

If the response from the SNMP agent is SNMP_ERROR_DPI_higherPriorityRegistered, then a DPI subagent has already registered the same subtree at a higher priority than requested in this call. If so, this subagent will be contained in the subagent Management Information Base (MIB), and using an appropriate SNMP management application, you can determine its priority. You may want to consider requesting a higher priority or even -1 (best available) for your subagent.

If the response from the SNMP agent is SNMP_ERROR_DPI_alreadyRegistered, then the requested subtree registration was for a portion of the overall MIB that is supported by an SNMP agent directly or by other system-implemented programs. Generally, registration of any subtree root, which would have the effect of masking all or portions of these subtrees (if allowed to occur), is prohibited.

Not all protected subtrees are currently supplied on the iSeries server, although most are. If a subtree is currently not supplied, then the first subagent that dynamically registers it will be allowed, and later subagents will be disallowed. Refer to the "i5/OS SNMP Agent Set Processing and Supported SNMP MIBs" in the Simple Network Management Protocol book for information on the MIB groups currently supplied with i5/OS.

Following are the protected subtrees and the associated MIB name:

Related Information

• The <qtossapi.h> file (see Header Files for UNIX-Type Functions)
  
  
• DPI_PACKET_LEN()--Get Length of DPI Packet
  
  
• fDPIparse()--Free Storage from DPI Packet Parse
  
  
• pDPIpacket()--Parse a DPI Packet

Example

See Code disclaimer information for information pertaining to code examples.

  #include <qtossapi.h>
  unsigned char *pack_p;

  pack_p = mkDPIregister(0,0L,"1.3.6.1.2.3.4.5.",
                         DPI_BULK_NO);
  if (pack_p) {
     /* Send packet to agent and await response. */
  }