mkDPIopen()--Make a DPI Open Packet

 #include <qtossapi.h>

 unsigned char     *mkDPIopen(
      char             *oid_p,
      char             *description_p,
      unsigned long    timeout,
      unsigned long    max_varbinds,
      char             character_set,
      unsigned long    password_len,
      unsigned char    *password_p );

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

Authorities and Locks

None.

Parameters

oid_p

(Input) A pointer to a NULL-terminated character string that represents the OBJECT IDENTIFIER, which uniquely identifies the subagent.

description_p

(Input) A pointer to a NULL-terminated character string, which is a descriptive name for the subagent. This can be any DisplayString, which basically is a byte string that contains only characters from the ASCII network virtual terminal (NVT) set.

timeout

(Input) The requested timeout for this subagent. An agent often has a limit for this value, and it will use that limit if this value is larger. A timeout of zero has a special meaning in the sense that the agent will then use its own default timeout value. The upper bound and default timeout values for DPI subagents are maintained by the SNMP agent in the subagent MIB. For details about the subagent MIB, see "SNMP Subagent MIB" in the Simple Network Management Protocol book.

max_varBinds

(Input) The maximum number of varbinds per DPI packet that the subagent is prepared to handle. The agent tries to combine up to this number of varbinds (belonging to the same subtree) in a single DPI packet. If zero is specified, there is no explicit upper bound on the number of varbinds. In all cases, the actual number of varbinds is constrained by buffer sizes.

character_set

(Input) The character set that you want to use for string-based data fields in the DPI packets and structures. In general, the SNMP agent communicates to all SNMP managers in NVT ASCII and stores information in its own MIBs in ASCII. However, the agent will do some translations. Currently, only DPI_NATIVE_CSET is supported. For the iSeries server, this is EBCDIC (coded character set identifier (CCSID) 500).

The specifics are as follows:

• On SET, COMMIT and UNDO requests from the agent, if the OID Structure of Management Information (SMI) type is SNMP_TYPE_OCTET_STRING and the textual convention is DisplayString, the agent will translate from ASCII to EBCDIC. The <qtossapi.h> file contains the C-language defines for these SMI types.

  Note: A subagent implementation with DisplayString OIDs that have read/write access should check the value_type in the snmp_dpi_set_packet (see the <qtossapi.h> file). If the value_type is not equal to the SNMP_TYPE_DisplayString in the set request, then the agent will not have converted from ASCII to EBCDIC. In this case, the subagent should perform the translation.

• If the textual convention is DisplayString during the processing of a GET or GETNEXT from a subagent, the agent will convert from EBCDIC to ASCII.
  
  
• When processing a DPI open packet, the agent will translate the description (see the description_p parameter) from EBCDIC to ASCII for storage in the subagent MIB.
  
  
• In the SNMP MIB II system group, there are a number of DisplayString OIDs. These are all stored in ASCII. (The Internet standard RFC 1213, "Management Information Base for Network Management of TCP/IP-based internets: MIB-II", defines MIB II and the system group as well as other groups.)

password_len

(Input) The length (in bytes) of an optional password. For the iSeries server agent, subagents do not need to supply a password. If not, then a zero length may be specified.

password_p

(Input) A pointer to an byte string that represents the password for this subagent. This corresponds to an SNMP agent community name. A password may include any character value, including the NULL character. If the password_len is zero, then this can be a NULL pointer.

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 mkDPIopen() function creates a serialized DPI OPEN 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 open 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 this DPI packet. The error_code should be checked.

If the error_code is SNMP_ERROR_DPI_duplicateSubAgentIdentifier, then another subagent with the same subagent OID has already sent an open DPI packet and the SA MIB OID saAllowDuplicateIDs is 2 (No). Either choose a different OID for this subagent, change saAllowDuplicateIDs to 1 (Yes) or stop the other subagent that has the requested identifier. The fDPIparse() function would normally be called after that to free the parsed DPI response packet. For information about saAllowDuplicateIDs, see "SNMP Subagent MIB" in the Simple Network Management Protocol book.

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 = mkDPIopen("1.3.6.1.2.3.4.5",
                "Sample DPI sub-agent"
                0L,2L, DPI_NATIVE_CSET,
                0,(char *)0);
  if (pack_p) {
     /* Send packet to the agent. */
  }