home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tolkit45.zip / os2tk45 / book / dpil1mst.inf (.txt) < prev    next >
OS/2 Help File  |  1999-05-12  |  149KB  |  5,821 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About This Book ΓòÉΓòÉΓòÉ
  3.  
  4. This book is designed as a programmer's guide for the IBM SystemView Agent 
  5. Version 1.4 program (hereafter referred to as SystemView Agent). The SystemView 
  6. Agent provides the Simple Network Management Protocol (SNMP) agent distributed 
  7. protocol interface (DPI). The SNMP DPI permits users to dynamically add, 
  8. delete, or replace management variables in the local Management Information 
  9. Base (MIB) without requiring you to recompile the SNMP agent. 
  10.  
  11.  
  12. ΓòÉΓòÉΓòÉ 1.1. Who Should Use This Book ΓòÉΓòÉΓòÉ
  13.  
  14. You should read this book if you are an agent programmer who will use 
  15. SystemView Agent. You should use this book if you are doing one or more of the 
  16. following: 
  17.  
  18.      Developing an SNMP subagent that uses the Distributed Protocol Interface 
  19.       (DPI) 2.0 
  20.  
  21.      Migrating your SNMP DPI subagent to Version 2.0 
  22.  
  23.  Before reading this book, you should have a general understanding of network 
  24.  management, the operating system on which you are working, and the C 
  25.  programming language. 
  26.  
  27.  In addition, you may want to obtain the following documents: 
  28.  
  29.      RFC1592 is the SNMP DPI 2.0 RFC. 
  30.      RFC1901 through RFC1910 are the SNMP Version 2 RFCs. 
  31.  
  32.  
  33. ΓòÉΓòÉΓòÉ 1.2. How to Use This Book ΓòÉΓòÉΓòÉ
  34.  
  35. Read Introduction to SNMP Distributed Protocol Interface for information about 
  36. the SNMP DPI routines supported by SystemView Agent and for information about 
  37. running a DPI API application. 
  38.  
  39. Read Subagent Programming Concepts for conceptual information about subagent 
  40. programming. This section contains detailed information on request processing 
  41. and contains specific programming recommendations. 
  42.  
  43. Read Basic DPI API Functions for information on these DPI functions, including 
  44. syntax and examples. 
  45.  
  46. Read Transport-Related DPI API Functions for information on each of the DPI 
  47. transport-related functions available.  These functions try to hide any 
  48. platform specific issues for the DPI subagent programmer so the subagent can be 
  49. made as portable as possible. The information includes syntax and examples. 
  50.  
  51. Read DPI Structures for information about each data structure used in the SNMP 
  52. DPI API. 
  53.  
  54. Read Character Set Selection for information about specifying the correct 
  55. character set. 
  56.  
  57. Read Constants, Values, Return Codes, and Include File for information about 
  58. constants and values as they are defined in the snmp_dpi.h include file. 
  59.  
  60. Read SNMP DPI API Version 1.1 Considerations for guidelines on programming with 
  61. Version 1.1. 
  62.  
  63. Read Migrating Your SNMP DPI Subagent to Version 2.0 for guidelines on 
  64. programming with Version 2.0. 
  65.  
  66. A DPI Subagent Example contains example code and comments that explain the 
  67. example program. 
  68.  
  69. This book also contains a glossary, a bibliography, and an index. 
  70.  
  71.  
  72. ΓòÉΓòÉΓòÉ 1.2.1. Highlighting and Operation Naming Conventions ΓòÉΓòÉΓòÉ
  73.  
  74. The following highlighting conventions are used in this book with the noted 
  75. exceptions: 
  76.  
  77.  Bold           Identifies menu choices, pushbuttons, commands, and shell 
  78.                 script paths (except in reference information), default values, 
  79.                 user selections, daemon paths (on first occurrence), and flags 
  80.                 (in parameter lists). 
  81.  
  82.  Italics        Identifies parameters whose actual names or values are to be 
  83.                 supplied by the user, and terms that are defined in the 
  84.                 following text. 
  85.  
  86.  Monospace      Identifies subjects of examples, messages in text, examples of 
  87.                 portions of program code, examples of text you might see 
  88.                 displayed, information you should actually type, and examples 
  89.                 used as teaching aids. 
  90.  
  91.  
  92. ΓòÉΓòÉΓòÉ 1.2.2. Terms and Abbreviations ΓòÉΓòÉΓòÉ
  93.  
  94. This book uses the following terms: 
  95.  
  96.  DPI                 Distributed Protocol Interface 
  97.  
  98.  MI                  Management Interface 
  99.  
  100.  MIF                 Management Information Format 
  101.  
  102.  RFC                 An abbreviation for Internet Request for Comments 
  103.                      documents 
  104.  
  105.  SNMP                Simple Network Management Protocol 
  106.  
  107.  
  108. ΓòÉΓòÉΓòÉ 1.3. Where to Find More Information ΓòÉΓòÉΓòÉ
  109.  
  110. The SystemView Agent worldwide web page can be accessed through the following 
  111. uniform resource locator (URL): http:// www.software.ibm.com/ 
  112. sysman/technology/caprod.html. See the web page for current updates and news 
  113. about the product. 
  114.  
  115. The following publications are included with the SystemView Agent program: 
  116.  
  117.      SystemView Agent User's Guide, SVAG-USR2 
  118.      SystemView Agent DMI Programmer's Guide, SVAG-DMIP 
  119.      SystemView Agent DPI Programmer's Guide, SVAG-DPIP 
  120.  
  121.  The documents included with SystemView Agent are available in softcopy format. 
  122.  For OS/2 installations, use the VIEW facility. 
  123.  
  124.  SystemView Agent supports the most current DMI specification. At this time, 
  125.  this is DMI Version 1.1. The Desktop Management Interface Specification, 
  126.  Version 1.1 is available from the Desktop Management Task Force. 
  127.  
  128.  Publications relevant to the SystemView Agent SNMP function are: 
  129.  
  130.      RFC1592, which is the SNMP DPI 2.0 RFC. 
  131.      RFC1157, which describes SNMP Version 1 
  132.      RFC1901 through RFC1910, which describe SNMP Version 2 
  133.  
  134.  Other sources of information that can be helpful when using SystemView Agent 
  135.  are listed in Bibliography. 
  136.  
  137.  You can request IBM publications from your IBM representative or the IBM 
  138.  branch office serving your region. You can also contact the place where you 
  139.  purchased the SystemView Agent program. 
  140.  
  141.  
  142. ΓòÉΓòÉΓòÉ 2. Introduction to SNMP Distributed Protocol Interface ΓòÉΓòÉΓòÉ
  143.  
  144. This section describes the SNMP DPI routines supported by SystemView Agent. 
  145. This Application Programming Interface (API) is for the DPI subagent 
  146. programmer. 
  147.  
  148. The reader may also want to obtain a copy of the relevant RFCs. 
  149.  
  150.      RFC1592 is the SNMP DPI 2.0 RFC. 
  151.      RFC1901 through RFC1910 are the SNMP Version 2 RFCs. 
  152.  
  153.  Topics 
  154.  
  155.       SNMP Agents and Subagents 
  156.       DPI Agent Requests 
  157.       Multiple Levels of the SNMP DPI API 
  158.       SNMP DPI API Source Files 
  159.       DPI Library 
  160.       Compiling, Linking, and Running a DPI API Application 
  161.       Functions, Data Structures, and Constants 
  162.  
  163.  
  164. ΓòÉΓòÉΓòÉ 2.1. SNMP Agents and Subagents ΓòÉΓòÉΓòÉ
  165.  
  166. SNMP agents are responsible for answering SNMP requests from network management 
  167. stations.  Examples of management requests are GET, GETNEXT, and SET, performed 
  168. on the MIB objects. 
  169.  
  170. A subagent extends the set of MIB objects provided by the SNMP agent.  With the 
  171. subagent, you define MIB variables useful in your own environment and register 
  172. them with the SNMP agent. 
  173.  
  174. When the agent receives a request for a MIB variable, it passes the request to 
  175. the subagent.  The subagent then returns a response to the agent.  The agent 
  176. creates an SNMP response packet and sends the response to the remote network 
  177. management station that initiated the request.  The existence of the subagent 
  178. is transparent to the network management station. 
  179.  
  180. To allow the subagents to perform these functions, the agent provides for two 
  181. types of subagent connections: 
  182.  
  183.      TCP connection 
  184.      Connection via Shared Memory (SHM) 
  185.  
  186.  For the TCP connections, the agent binds to an arbitrarily chosen TCP port and 
  187.  listens for connection requests.  A well-known port is not used.  Every 
  188.  invocation of the SNMP agent could potentially use a different TCP port. 
  189.  
  190.  A subagent of the SNMP agent determines the port number by sending a GET 
  191.  request for an MIB variable, which represents the value of the TCP port.  The 
  192.  subagent is not required to create and parse SNMP packets because the DPI API 
  193.  has a library routine query_DPI_port().  After the subagent obtains the value 
  194.  of the DPI TCP port, it should make a TCP connection to the appropriate port. 
  195.  After a successful connect(), the subagent registers the set of variables it 
  196.  supports with the SNMP agent.  When all variable classes are registered, the 
  197.  subagent waits for requests from the SNMP agent. 
  198.  
  199.  The query_DPI_port() function is implicitly executed by the 
  200.  DPIconnect_to_agent_TCP() function.  The DPI subagent programmer would 
  201.  normally use the DPIconnect_to_agent_TCP() function to connect to the agent, 
  202.  so it does not need to obtain the value of the DPI TCP port. 
  203.  
  204.  For a SHM connection, the subagent can use the DPIconnect_to_agent_SHM() 
  205.  function. 
  206.  
  207.  
  208. ΓòÉΓòÉΓòÉ 2.2. DPI Agent Requests ΓòÉΓòÉΓòÉ
  209.  
  210. The SNMP agent can initiate several DPI requests: 
  211.  
  212.      GET 
  213.      GETNEXT 
  214.      GETBULK (SNMP Version 2) 
  215.      SET, COMMIT, and UNDO 
  216.      UNREGISTER 
  217.      CLOSE 
  218.  
  219.  The GET, GETNEXT, GETBULK, and SET requests correspond to the SNMP requests 
  220.  that a network management station can make.  The subagent responds to a 
  221.  request with a response packet.  The response packet can be created using the 
  222.  mkDPIresponse() library routine, which is part of the DPI API library. 
  223.  
  224.  The GETBULK requests are translated into multiple GETNEXT requests by the 
  225.  agent.  According to RFC 1592, a subagent may request that the GETBULK be 
  226.  passed to it, but the OS/2 implementation of SystemView Agent does not support 
  227.  that request. 
  228.  
  229.  The COMMIT, UNDO, UNREGISTER, and CLOSE are specific SNMP DPI requests. 
  230.  
  231.  The subagent normally responds to a request with a RESPONSE packet. For the 
  232.  CLOSE and UNREGISTER request, the subagent does not need to send a RESPONSE. 
  233.  
  234.  Related Information 
  235.  
  236.       Overview of Subagent Processing 
  237.       Connecting to the Agent 
  238.       Registering a Sub-Tree with the Agent 
  239.       Processing Requests from the Agent 
  240.       Processing a GET Request 
  241.       Processing a GETNEXT Request 
  242.       Processing a SET/COMMIT/UNDO Request 
  243.       Processing an UNREGISTER Request 
  244.       Processing a CLOSE Request 
  245.       Generating a TRAP 
  246.  
  247.  
  248. ΓòÉΓòÉΓòÉ 2.3. Multiple Levels of the SNMP DPI API ΓòÉΓòÉΓòÉ
  249.  
  250. For the SNMP DPI 2.0 API, some functions are implemented as macros, because the 
  251. older DPI Version 1.x had the same function names with different parameters. 
  252. The new implementation has new function names, which are not always the most 
  253. intuitive.  By defining the macros with the more natural names for the 
  254. functions, the non-intuitive names are hidden.  This was done because the 
  255. macros have the same names as the functions were named in DPI Version 1.  It is 
  256. thus possible to provide either the DPI 1.x or the DPI 2.x API by properly 
  257. defining the macros. 
  258.  
  259.  
  260. ΓòÉΓòÉΓòÉ 2.3.1. SNMP DPI API Version 2.0 ΓòÉΓòÉΓòÉ
  261.  
  262. By default, when you include the snmp_dpi.h include file, you will be exposed 
  263. to the DPI 2.0 API.  For a list of the functions provided, see The snmp_dpi.h 
  264. Include File. This is the recommended use of the SNMP DPI API.  When you 
  265. link-edit your object code into an executable file, you must use the new DPI 
  266. functions as provided in the DPI20DLL.LIB and DPI20DLL.DLL files. 
  267.  
  268. Waiting for a DPI packet also depends on the platform and how the chosen 
  269. transport protocol is exactly implemented.  In addition, some subagents want to 
  270. control sending of and waiting for packets themselves, because they may need to 
  271. be driven by other interrupts as well. 
  272.  
  273. There is a set of DPI transport-related functions that are implemented on all 
  274. platforms to hide the platform dependent issues for those subagents that do not 
  275. need detailed control about the transport themselves. 
  276.  
  277.  
  278. ΓòÉΓòÉΓòÉ 2.3.2. Compatibility with DPI 1.x Base Code ΓòÉΓòÉΓòÉ
  279.  
  280. If you have DPI 1.x based code, you may choose to keep using the old DPI 1.x 
  281. dpi\snmp_dpi.h include file and the old DPI 1.x functions as provided in 
  282. DPI32DLL.LIB and DPI32DLL.DLL.  You will be able to communicate with the OS/2 
  283. SNMP agent which implements DPI 2.0. 
  284.  
  285. In Migrating Your DPI Subagent to DPI 2.0, the changes that you must make to 
  286. your DPI 1.x source are presented.  If you take a few minutes to look at it, 
  287. you will see that this is not too big a task. 
  288.  
  289.  
  290. ΓòÉΓòÉΓòÉ 2.4. SNMP DPI API Source Files ΓòÉΓòÉΓòÉ
  291.  
  292. The following source files are provided: 
  293.  
  294.  snmp_dpi.h       The public SNMP DPI 2.0 API as provided to the DPI subagent 
  295.                   programmer.  The DPI subagent code must include this file. 
  296.  
  297.  dpi_samp.c       A very basic example of an SNMP DPI 2.0 subagent 
  298.                   implementation, dpiSimp.mib. 
  299.  
  300.  dpiSimp.mib      The dpiSimple MIB that goes with the dpi_samp.c source. 
  301.  
  302.  The DPI subagent programmer can use the snmp_dpi.h include file and the 
  303.  dpi_samp.c file as an example of using the DPI API. 
  304.  
  305.  
  306. ΓòÉΓòÉΓòÉ 2.5. DPI Library ΓòÉΓòÉΓòÉ
  307.  
  308. To use the DPI library routines provided with SystemView Agent, you must have 
  309. the <snmp_dpi.h> header file in your SVA\DPI directory. 
  310.  
  311. The DPI20DLL.LIB file in the SVA\DPI directory contains the DPI library 
  312. routines.  You must also have the SO32DLL.LIB and TCP32DLL.LIB files, which are 
  313. provided by the OS/2 TCP/IP programmers toolkit. 
  314.  
  315. You must define the OS2 variable to the compiler by doing one of the following: 
  316.  
  317.      Place #define OS2 at the top of each file that includes TCP/IP header 
  318.       files. 
  319.  
  320.      Use the /DOS2 option when compiling the source for your application. 
  321.  
  322.  See the SVA\DPI directory for SNMP DPI sample programs. 
  323.  
  324.  
  325. ΓòÉΓòÉΓòÉ 2.6. Compiling, Linking, and Running a DPI API Application ΓòÉΓòÉΓòÉ
  326.  
  327. Note:  :The proper environment variables were set in the CONFIG.SYS file during 
  328. installation. 
  329.  
  330. The compiling and linking procedure for the DPI API using an IBM 32-bit 
  331. compiler for OS/2 follows: 
  332.  
  333.    1. To compile the program, enter: 
  334.  
  335.             icc /Sa /j- /Gm /C myprog.c
  336.  
  337.    2. To create an executable program, you can enter: 
  338.  
  339.       For VisualAge C++ 
  340.  
  341.             ilink /NOFREEFORMAT /De myprog,myprog.exe,NULL,so32dll.lib tcp32dll.lib
  342.             os2386 dpi20dll.lib
  343.  
  344.       For C Set++ 
  345.  
  346.             link386 /De myprog,myprog.exe,NULL,so32dll.lib tcp32dll.lib
  347.             os2386 dpi20dll.lib
  348.  
  349.  For more information about the compile and link options, see the User's Guide 
  350.  provided with your compiler. 
  351.  
  352.  
  353. ΓòÉΓòÉΓòÉ 2.7. Functions, Data Structures, and Constants ΓòÉΓòÉΓòÉ
  354.  
  355. Use these lists to locate the descriptions for the functions, data structures, 
  356. and constants. 
  357.  
  358. Basic DPI Functions: 
  359.  
  360.       The DPIdebug() Function 
  361.       The DPI_PACKET_LEN() macro 
  362.       The fDPIparse() Function 
  363.       The fDPIset() Function 
  364.       The mkDPIAreYouThere() Function 
  365.       The mkDPIclose() Function 
  366.       The mkDPIopen() Function 
  367.       The mkDPIregister() Function 
  368.       The mkDPIresponse() Function 
  369.       The mkDPIset() Function 
  370.       The mkDPItrap() Function 
  371.       The mkDPIunregister() Function 
  372.       The pDPIpacket() Function 
  373.  
  374.  DPI Transport-Related Functions: 
  375.  
  376.       The DPIawait_packet_from_agent() Function 
  377.       The DPIconnect_to_agent_SHM() Function 
  378.       The DPIconnect_to_agent_TCP() Function 
  379.       The DPIdisconnect_from_agent() Function 
  380.       The DPIget_fd_for_handle() Function 
  381.       The DPIsend_packet_to_agent() Function 
  382.       The lookup_host() Function 
  383.       The query_DPI_port() Function 
  384.  
  385.  Data Structures: 
  386.  
  387.       The snmp_dpi_bulk_packet structure 
  388.       The snmp_dpi_close_packet structure 
  389.       The snmp_dpi_get_packet structure 
  390.       The snmp_dpi_next_packet structure 
  391.       The snmp_dpi_hdr structure 
  392.       The snmp_dpi_resp_packet structure 
  393.       The snmp_dpi_set_packet structure 
  394.       The snmp_dpi_ureg_packet structure 
  395.       The snmp_dpi_u64 structure 
  396.  
  397.  Constants and Values: 
  398.  
  399.       DPI CLOSE Reason Codes 
  400.       DPI Packet Types 
  401.       DPI RESPONSE Error Codes 
  402.       DPI UNREGISTER Reason Codes 
  403.       DPI SNMP Value Types 
  404.       Value Representation 
  405.  
  406.  Related Information: 
  407.  
  408.       Character Set Selection 
  409.       The snmp_dpi.h Include File 
  410.  
  411.  
  412. ΓòÉΓòÉΓòÉ 3. Subagent Programming Concepts ΓòÉΓòÉΓòÉ
  413.  
  414. This section contains conceptual information about subagent programming. 
  415.  
  416. Topics 
  417.  
  418.       Programming Recommendations 
  419.       DPI API 
  420.       GET Processing 
  421.       SET Processing 
  422.       GETNEXT Processing 
  423.       GETBULK Processing 
  424.       OPEN Request 
  425.       CLOSE Request 
  426.       REGISTER Request 
  427.       UNREGISTER Request 
  428.       TRAP Request 
  429.       ARE_YOU_THERE Request 
  430.       Multithreading Programming Considerations 
  431.  
  432.  
  433. ΓòÉΓòÉΓòÉ 3.1. Programming Recommendations ΓòÉΓòÉΓòÉ
  434.  
  435. When implementing a subagent, it is recommended that you use the DPI Version 2 
  436. approach.  This includes: 
  437.  
  438.      Use the SNMP Version 2 error codes only, even though there are 
  439.       definitions for the SNMP Version 1 error codes. 
  440.  
  441.      Implement the SET, COMMIT, UNDO processing properly. 
  442.  
  443.      For GET requests, use the SNMP Version 2 approach and pass back 
  444.       noSuchInstance value or noSuchObject value if appropriate.  Continue to 
  445.       process all remaining varBinds. 
  446.  
  447.      For GETNEXT, use the SNMP Version 2 approach and pass back endOfMibView 
  448.       value if appropriate.  Continue to process all remaining varBinds. 
  449.  
  450.      When you are processing a request from the agent (GET, GETNEXT, GETBULK, 
  451.       SET, COMMIT, or UNDO), you are supposed to respond within the timeout 
  452.       period.  You can specify the timeout period in the OPEN and REGISTER 
  453.       packets. 
  454.  
  455.       If you fail to respond within the timeout period, the agent will probably 
  456.       close your DPI connection and then discard your RESPONSE packet if it 
  457.       comes in later.  If you can detect that the response is not going to be 
  458.       received in the time period, then you might decide to stop the request 
  459.       and return an SNMP_ERROR_genErr in the RESPONSE. 
  460.  
  461.      You may want to issue an SNMP DPI ARE_YOU_THERE request periodically to 
  462.       ensure that the agent is still "connected" and still knows about you. 
  463.  
  464.      For OS/2, you use an ASCII based machine.  However, when you are running 
  465.       on an EBCDIC based machine and you use the (default) native character 
  466.       set, then all OID strings and all variable values of type 
  467.       OBJECT_IDENTIFIER or DisplayString will be passed to you in EBCDIC 
  468.       format.  OID strings include the group ID, instance ID, Enterprise ID, 
  469.       and subagent ID. 
  470.  
  471.       When you return a response, you should then also use EBCDIC FORMAT. 
  472.  
  473.      For OS/2, you use an ASCII based machine.  However, when you are running 
  474.       on an EBCDIC based machine and you use the ASCII character set (specified 
  475.       in DPI OPEN), then all OID strings and all variable values of type 
  476.       OBJECT_IDENTIFIER or DisplayString will be passed to you in ASCII format. 
  477.       OID strings include the group ID, instance ID, Enterprise ID, and 
  478.       subagent ID. 
  479.  
  480.       When you return a response, you should then also use ASCII FORMAT. 
  481.  
  482.      If you receive an error RESPONSE on the OPEN packet, you will also 
  483.       receive a DPI CLOSE packet with an SNMP_CLOSE_openError code.  In this 
  484.       situation, the agent closes the "connection". 
  485.  
  486.       For OS/2, you use an ASCII based machine.  However, when you connect to 
  487.       an EBCDIC based agent, you may want to specify in the DPI OPEN packet 
  488.       that you want to use ASCII character set on the agent.  This is 
  489.       transparent to you and the burden of conversion is on the EBCDIC based 
  490.       agent. 
  491.  
  492.      The DisplayString is only a textual convention.  In the SNMP PDU (SNMP 
  493.       packet), the type is just an OCTET_STRING. 
  494.  
  495.       When the type is OCTET_STRING, it is not clear if this is a DisplayString 
  496.       or any arbitrary data.  This means that the agent can only know about an 
  497.       object being a DisplayString if the object is included in some sort of a 
  498.       compiled MIB.  If it is, the agent will use SNMP_TYPE_DisplayString in 
  499.       the type field of the varBind in a DPI SET packet.  When you send a 
  500.       DisplayString in a RESPONSE packet, the agent will handle it as such. 
  501.  
  502.  Related Information 
  503.  
  504.       A DPI Subagent Example 
  505.  
  506.  
  507. ΓòÉΓòÉΓòÉ 3.2. DPI API ΓòÉΓòÉΓòÉ
  508.  
  509. The primary goal of RFC 1592 is to specify the SNMP DPI.  This is a protocol by 
  510. which subagents can exchange SNMP related information with an agent.  On top of 
  511. this protocol, one can imagine one or possibly many Application Programming 
  512. Interfaces, but those are not addressed in RFC 1592. 
  513.  
  514. In order to provide an environment that is generally platform independent, RFC 
  515. 1592 strongly suggests that you also define a DPI API.  There is a sample DPI 
  516. API available in the RFC.  The document describes the same sample API as the 
  517. IBM supported DPI Version 2.0 API, see A DPI Subagent Example. 
  518.  
  519.  
  520. ΓòÉΓòÉΓòÉ 3.3. GET Processing ΓòÉΓòÉΓòÉ
  521.  
  522. The DPI GET packet holds one or more varBinds that the subagent has taken 
  523. responsibility for. 
  524.  
  525. If the subagent encounters an error while processing the request, it creates a 
  526. DPI RESPONSE packet with an appropriate error indication in the error_code 
  527. field and sets the error_index to the position of the varBind at which the 
  528. error occurs.  The first varBind is index 1, the second varBind is index 2, and 
  529. so on.  No name, type, length, or value information needs to be provided in the 
  530. packet because, by definition, the varBind information is the same as in the 
  531. request to which this is a response and the agent still has that information. 
  532.  
  533. If there are no errors, the subagent creates a DPI RESPONSE packet in which the 
  534. error_code is set to SNMP_ERROR_noError (zero) and error_index is set to zero. 
  535. The packet must also include the name, type, length, and value of each varBind 
  536. requested. 
  537.  
  538. When you get a request for a non-existing object or a non-existing instance of 
  539. an object, you must return a NULL value with a type of SNMP_TYPE_noSuchObject 
  540. or SNMP_TYPE_noSuchInstance respectively.  These two values are not considered 
  541. errors, so the error_code and error_index should be zero. 
  542.  
  543. The DPI RESPONSE packet is then sent back to the agent. 
  544.  
  545. Related Information 
  546.  
  547.       Processing a GET Request 
  548.       The mkDPIresponse() Function 
  549.  
  550.  
  551. ΓòÉΓòÉΓòÉ 3.4. SET Processing ΓòÉΓòÉΓòÉ
  552.  
  553. A DPI SET packet contains the name, type, length, and value of each varBind 
  554. requested, plus the value type, value length, and value to be set. 
  555.  
  556. If the subagent encounters an error while processing the request, it creates a 
  557. DPI RESPONSE packet with an appropriate error indication in the error_code 
  558. field and an error_index listing the position of the varBind at which the error 
  559. occurs.  The first varBind is index 1, the second varBind is index 2, and so 
  560. on.  No name, type, length, or value information needs to provided in the 
  561. packet because, by definition, the varBind information is the same as in the 
  562. request to which this is a response and the agent still has that information. 
  563.  
  564. If there are no errors, the subagent creates a DPI RESPONSE packet in which the 
  565. error_code is set to SNMP_ERROR_noError (zero) and error_index is set to zero. 
  566. No name, type, length, or value information is needed because the RESPONSE to a 
  567. SET should contain exactly the same varBind data as the data present in the 
  568. request.  The agent can use the values it already has. 
  569.  
  570. This suggests that the agent must keep state information, and that is the case. 
  571. It needs to do that anyway in order to be able to later pass the data with a 
  572. DPI COMMIT or DPI UNDO packet.  Since there are no errors, the subagent must 
  573. have allocated the required resources and prepared itself for the SET.  It does 
  574. not yet carry out the set, that will be done at COMMIT time. 
  575.  
  576. The subagent sends a DPI RESPONSE packet, indicating success or failure for the 
  577. preparation phase, back to the agent.  The agent will issue a SET request for 
  578. all other varBinds in the same original SNMP request it received.  This may be 
  579. to the same subagent or to one or more different subagents. 
  580.  
  581. Once all SET requests have returned a "no error" condition, the agent starts 
  582. sending DPI COMMIT packets to the subagent(s).  If any SET request returns an 
  583. error, the agent sends DPI UNDO packets to those subagents that indicated 
  584. successful processing of the SET preparation phase. 
  585.  
  586. When the subagent receives the DPI COMMIT packet, all the varBind information 
  587. will again be available in the packet.  The subagent can now carry out the SET 
  588. request. 
  589.  
  590. If the subagent encounters an error while processing the COMMIT request, it 
  591. creates a DPI RESPONSE packet with value SNMP_ERROR_commitFailed in the 
  592. error_code field and an error_index that lists at which varBind the error 
  593. occurs.  The first varBind is index 1, and so on.  No name, type, length, or 
  594. value information is needed.  The fact that a commitFailed error exists does 
  595. not mean that this error should be returned easily.  A subagent should do all 
  596. that is possible to make a COMMIT succeed. 
  597.  
  598. If there are no errors and the SET and COMMIT have been carried out with 
  599. success, the subagent creates a DPI RESPONSE packet in which the error_code is 
  600. set to SNMP_ERROR_noError (zero) and error_index is set to zero.  No name, 
  601. type, length, or value information is needed. 
  602.  
  603. So far we have discussed a successful SET and COMMIT sequence. However, after a 
  604. successful SET, the subagent may receive a DPI UNDO packet.  The subagent must 
  605. now undo any preparations it made during the SET processing, such as free 
  606. allocated memory. 
  607.  
  608. Even after a COMMIT, a subagent may still receive a DPI UNDO packet.  This will 
  609. occur if some other subagent could not complete a COMMIT request.  Because of 
  610. the SNMP requirement that all varBinds in a single SNMP SET request must be 
  611. changed "as if simultaneous", all committed changes must be undone if any of 
  612. the COMMIT requests fail. In this case the subagent must try and undo the 
  613. committed SET operation. 
  614.  
  615. If the subagent encounters an error while processing the UNDO request, it 
  616. creates a DPI RESPONSE packet with value SNMP_ERROR_undoFailed in the 
  617. error_code field and an error_index that lists at which varBind the error 
  618. occurs.  The first varBind is index 1, and so on.  No name, type, length, or 
  619. value information is needed.  The fact that an undoFailed error exists does not 
  620. mean that this error should be returned easily.  A subagent should do all that 
  621. is possible to make an UNDO succeed. 
  622.  
  623. If there are no errors and the UNDO has been successful, the subagent creates a 
  624. DPI RESPONSE packet in which the error_code is set to SNMP_ERROR_noError (zero) 
  625. and error_index is set to zero.  No name, type, length, or value information is 
  626. needed. 
  627.  
  628. Related Information 
  629.  
  630.       Processing a SET/COMMIT/UNDO Request 
  631.  
  632.  
  633. ΓòÉΓòÉΓòÉ 3.5. GETNEXT Processing ΓòÉΓòÉΓòÉ
  634.  
  635. The DPI GETNEXT packet contains the object(s) on which the GETNEXT operation 
  636. must be performed.  For this operation, the subagent is to return the name, 
  637. type, length, and value of the next variable it supports whose (ASN.1) name 
  638. lexicographically follows the one passed in the group ID (sub-tree) and 
  639. instance ID. 
  640.  
  641. In this case, the instance ID may not be present (NULL) in the incoming DPI 
  642. packet implying that the NEXT object must be the first instance of the first 
  643. object in the sub-tree that was registered. 
  644.  
  645. It is important to realize that a given subagent may support several 
  646. discontiguous sections of the MIB tree.  In that situation, it would be 
  647. incorrect to jump from one section to another.  This problem is correctly 
  648. handled by examining the group ID in the DPI packet.  This group ID represents 
  649. the "reason" why the subagent is being called.  It holds the prefix of the tree 
  650. that the subagent had indicated it supported (registered). 
  651.  
  652. If the next variable supported by the subagent does not begin with that prefix, 
  653. the subagent must return the same object instance as in the request, for 
  654. example the group ID and instance ID with a value of SNMP_TYPE_endOfMibView 
  655. (implied NULL value).  This endOfMibView is not considered an error, so the 
  656. error_code and error_index should be zero. If required, the SNMP agent will 
  657. call upon the subagent again, but pass it a different group ID (prefix).  This 
  658. is illustrated in the discussion below. 
  659.  
  660. Assume there are two subagents.  The first subagent registers two distinct 
  661. sections of the tree:  A and C.  In reality, the subagent supports variables 
  662. A.1 and A.2, but it correctly registers the minimal prefix required to uniquely 
  663. identify the variable class it supports. 
  664.  
  665. The second subagent registers section B, which appears between the two sections 
  666. registered by the first agent. 
  667.  
  668. If a management station begins browsing the MIB, starting from A, the following 
  669. sequence of queries of the form get-next(group ID,instance ID) would be 
  670. performed: 
  671.  
  672.   Subagent 1 gets called:
  673.          get-next(A,none) = A.1
  674.          get-next(A,1)    = A.2
  675.          get-next(A,2)    = endOfMibView
  676.  
  677.   Subagent 2 is then called:
  678.          get-next(B,none) = B.1
  679.          get-next(B,1)    = endOfMibView
  680.  
  681.   Subagent 1 gets called again:
  682.          get-next(C,none) = C.1
  683.  
  684. Related Information 
  685.  
  686.       Processing a GETNEXT Request 
  687.  
  688.  
  689. ΓòÉΓòÉΓòÉ 3.6. GETBULK Processing ΓòÉΓòÉΓòÉ
  690.  
  691. You can ask the agent to translate GETBULK requests into multiple GETNEXT 
  692. requests.  This is basically the default and is specified in the DPI REGISTER 
  693. packet.  In principle, we expect the majority of DPI subagents to run on the 
  694. same machine as the agent, or on the same physical network.  Therefore, 
  695. repetitive GETNEXT requests remain local and, in general, should not be a 
  696. problem. 
  697.  
  698. Otherwise, the subagent can tell the agent to pass on a DPI GETBULK packet. 
  699.  
  700. When a GETBULK request is received, the subagent must process the request and 
  701. send a RESPONSE that sends back as many varBinds as requested by the request, 
  702. as long as they fit within the buffers. 
  703.  
  704. The GETBULK requires similar processing as a GETNEXT with regard to 
  705. endOfMibView handling. 
  706.  
  707. Note:  A subagent cannot select GETBULK on OS/2.  It will always be translated 
  708. into multiple GETNEXT requests. 
  709.  
  710. Related Information 
  711.  
  712.       Processing a GETNEXT Request 
  713.  
  714.  
  715. ΓòÉΓòÉΓòÉ 3.7. OPEN Request ΓòÉΓòÉΓòÉ
  716.  
  717. As the first step, a DPI subagent must open a "connection" with the agent.  To 
  718. do so, it must send a DPI OPEN packet in which these parameters must be 
  719. specified: 
  720.  
  721.      The maximum timeout value in seconds.  The agent is requested to wait 
  722.       this long for a response to any request for an object being handled by 
  723.       this subagent. 
  724.  
  725.       The agent may have an absolute maximum timeout value which will be used 
  726.       if the subagent asks for too large a timeout value.  A value of zero can 
  727.       be used to indicate that the agent's own default timeout value should be 
  728.       used.  A subagent is advised to use a reasonably short interval of a few 
  729.       seconds or so.  If a specific sub-tree needs a (much) longer time, a 
  730.       specific REGISTER can be done for that sub-tree with a longer timeout 
  731.       value. 
  732.  
  733.      The maximum number of varBinds that the subagent is prepared to handle 
  734.       per DPI packet.  Specifying 1 would result in DPI Version 1 behavior of 
  735.       one varBind per DPI packet that the agent sends to the subagent.  A value 
  736.       of zero means the agent will try to combine up to as many varBinds as are 
  737.       present in the SNMP packet that belongs to the same sub-tree. 
  738.  
  739.      The character set you want to use.  By default, a 0 value, which is the 
  740.       native character set of the machine platform where the agent runs. Since 
  741.       the subagent and agent normally run on the same system or platform, you 
  742.       want to use the native character set, which is ASCII on many platforms. 
  743.  
  744.       If your platform is EBCDIC based, using the native character set of 
  745.       EBCDIC makes it easy to recognize the string representations of the 
  746.       fields, such as the group ID and instance ID.  At the same time, the 
  747.       agent will translate the value from ASCII NVT to EBCDIC and vice versa 
  748.       for objects that it knows from a compiled MIB to have a textual 
  749.       convention of DisplayString.  This fact cannot be determined from the 
  750.       SNMP PDU encoding because in the PDU the object is only known to be an 
  751.       OCTET_STRING. 
  752.  
  753.       If your subagent runs on an ASCII based platform and the agent runs on an 
  754.       EBCDIC based platform (or the other way around), you can specify that you 
  755.       want to use the ASCII character set.  The agent and subagent programmer 
  756.       knows how to handle the string-based data in this situation. 
  757.  
  758.       Note:  Not all agents need to support other than native character set 
  759.       selections.  See Character Set Selection for more information on 
  760.       character set usage. 
  761.  
  762.      The subagent ID.  This an ASN.1 Object Identifier that uniquely 
  763.       identifies the subagent.  This OID is represented as a null terminated 
  764.       string using the selected character set. 
  765.  
  766.       For example: "1.3.5.1.2.3.4.5" 
  767.  
  768.      The subagent description.  This is a DisplayString describing the 
  769.       subagent.  This is a character string using the selected character set. 
  770.  
  771.       For example: "DPI sample subagent Version 2.0" 
  772.  
  773.  Once a subagent has sent a DPI OPEN packet to an agent, it should expect a DPI 
  774.  RESPONSE packet that informs the subagent about the result of the request. 
  775.  The packet ID of the RESPONSE packet should be the same as that of the OPEN 
  776.  request to which the RESPONSE packet is the response.  See DPI RESPONSE Error 
  777.  Codes for a list of valid codes that may be expected. 
  778.  
  779.  If you receive an error RESPONSE on the OPEN packet, you will also receive a 
  780.  DPI CLOSE packet with an SNMP_CLOSE_openError code.  In this situation, the 
  781.  agent closes the "connection". 
  782.  
  783.  If the OPEN is accepted, the next step is to REGISTER one or more MIB 
  784.  sub-trees. 
  785.  
  786.  Related Information 
  787.  
  788.       Connecting to the Agent 
  789.  
  790.  
  791. ΓòÉΓòÉΓòÉ 3.8. CLOSE Request ΓòÉΓòÉΓòÉ
  792.  
  793. When a subagent is finished and wants to end processing, it should first 
  794. UNREGISTER its sub-trees and then close the "connection" with the agent.  To do 
  795. so, it must send a DPI CLOSE packet, which specifies a reason for the closing. 
  796. See DPI CLOSE Reason Codes for a list of valid codes.  You should not expect a 
  797. response to the CLOSE request. 
  798.  
  799. A subagent should also be prepared to handle an incoming DPI CLOSE packet from 
  800. the agent.  In this case, the packet will contain a reason code for the CLOSE 
  801. request.  A subagent does not have to send a response to a CLOSE request.  The 
  802. agent just assumes that the subagent will handle it appropriately.  The close 
  803. takes place regardless of what the subagent does with it. 
  804.  
  805. Related Information 
  806.  
  807.       Processing an CLOSE Request 
  808.  
  809.  
  810. ΓòÉΓòÉΓòÉ 3.9. REGISTER Request ΓòÉΓòÉΓòÉ
  811.  
  812. Before a subagent will receive any requests for MIB variables, it must first 
  813. register the variables or sub-tree it supports with the SNMP agent.  The 
  814. subagent must specify a number of parameters in the REGISTER request: 
  815.  
  816.      The sub-tree to be registered.  This is a null terminated string in the 
  817.       selected character set.  The sub-tree must have a trailing dot. 
  818.  
  819.       For example: "1.3.6.1.2.3.4.5." 
  820.  
  821.      The requested priority for the registration.  The values are: 
  822.  
  823.       -1            Request for the best available priority. 
  824.  
  825.        0            Request for the next best available priority than the 
  826.                     highest (best) priority currently registered for this 
  827.                     sub-tree. 
  828.  
  829.       NNN           Any other positive value requests that specific priority if 
  830.                     available or the next worse priority that is available. 
  831.  
  832.      The maximum timeout value in seconds.  The agent is requested to wait 
  833.       this long for a response to any request for an object in this sub-tree. 
  834.       The agent may have an absolute maximum timeout value which will be used 
  835.       if the subagents asks for too large a timeout value.  A value of zero can 
  836.       be used to indicate that the DPI OPEN value should be used for timeout. 
  837.  
  838.      A specification if the subagent wants to do view selection.  If it does, 
  839.       the community name from SNMP Version 1 packets will be passed in the DPI 
  840.       GET, GETNEXT, and SET packets.  This is not supported on OS/2. 
  841.  
  842.      A specification if the subagent wants to receive GETBULK packets or if it 
  843.       just prefers that the agent converts a GETBULK into multiple GETNEXT 
  844.       requests.  This is not supported on OS/2. 
  845.  
  846.  Once a subagent has sent a DPI REGISTER packet to the agent, it should expect 
  847.  a DPI RESPONSE packet that informs the subagent about the result of the 
  848.  request.  The packet ID of the RESPONSE packet should be the same as that of 
  849.  the REGISTER packet to which the RESPONSE packet is the response. 
  850.  
  851.  If the response is successful, the error_index field in the RESPONSE packet 
  852.  contains the priority that the agent assigned to the sub-tree registration. 
  853.  See DPI RESPONSE Error Codes for a list of valid codes that may be expected. 
  854.  
  855.  Error Code: higherPriorityRegistered 
  856.  
  857.  The response to a REGISTER request may return the error code 
  858.  "higherPriorityRegistered".  This may be caused by: 
  859.  
  860.      Another subagent already registered the same sub-tree at a better 
  861.       priority than what you are requesting. 
  862.  
  863.      Another subagent already registered a sub-tree at a higher level (at any 
  864.       priority). For instance, if a registration already exists for sub-tree 
  865.       1.2.3.4.5.6 and you try to register for sub-tree 1.2.3.4.5.6.<anything> 
  866.       then you will get "higherPriorityRegistered" error code. 
  867.  
  868.  If you receive this error code, your sub-tree will be registered, but you will 
  869.  not see any requests for the sub-tree.  They will be passed to the sub-agent 
  870.  which registered with a better priority.  If you stay connected, and the other 
  871.  sub-agent goes away, then you will get control over the sub-tree at that point 
  872.  in time. 
  873.  
  874.  Related Information 
  875.  
  876.       Registering a Sub-Tree with the Agent 
  877.  
  878.  
  879. ΓòÉΓòÉΓòÉ 3.10. UNREGISTER Request ΓòÉΓòÉΓòÉ
  880.  
  881. A subagent may unregister a previously registered sub-tree.  The subagent must 
  882. specify a few parameters in the UNREGISTER request: 
  883.  
  884.      The sub-tree to be unregistered.  This is a null terminated string in the 
  885.       selected character set.  The sub-tree must have a trailing dot. 
  886.  
  887.       For example: "1.3.6.1.2.3.4.5." 
  888.  
  889.      The reason for the unregister.  See DPI UNREGISTER Reason Codes for a 
  890.       list of valid reason codes. 
  891.  
  892.  Once a subagent has sent a DPI UNREGISTER packet to the agent, it should 
  893.  expect a DPI RESPONSE packet that informs the subagent about the result of the 
  894.  request.  The packet ID of the RESPONSE packet should be the same as that of 
  895.  the REGISTER packet to which the RESPONSE packet is the response.  See DPI 
  896.  RESPONSE Error Codes for a list of valid codes that may be expected. 
  897.  
  898.   A subagent should also be prepared to handle incoming DPI UNREGISTER packets 
  899.  from the agent.  In this situation, the DPI packet will contain a reason code 
  900.  for the UNREGISTER.  A subagent does not have to send a response to an 
  901.  UNREGISTER request.  The agent just assumes that the subagent will handle it 
  902.  appropriately.  The registration is removed regardless of what the subagent 
  903.  returns. 
  904.  
  905.  Related Information 
  906.  
  907.       Processing an UNREGISTER Request 
  908.  
  909.  
  910. ΓòÉΓòÉΓòÉ 3.11. TRAP Request ΓòÉΓòÉΓòÉ
  911.  
  912. A subagent can request that the SNMP agent generates a trap for it. The 
  913. subagent must provide the desired values for the generic and specific 
  914. parameters of the trap.  It may optionally provide a set of one or more name, 
  915. type, length, or value parameters that will be included in the trap packet. 
  916.  
  917. It may optionally specify an Enterprise ID (Object Identifier) for the trap to 
  918. be generated.  If a NULL value is specified for the Enterprise ID, the agent 
  919. will use the subagent Identifier from the DPI OPEN packet as the Enterprise ID 
  920. to be sent with the trap. 
  921.  
  922. Related Information 
  923.  
  924.       Generating a TRAP 
  925.  
  926.  
  927. ΓòÉΓòÉΓòÉ 3.12. ARE_YOU_THERE Request ΓòÉΓòÉΓòÉ
  928.  
  929. A subagent can send an ARE_YOU_THERE packet to the agent.  This may be useful 
  930. to do if you have a DPI "connection" over an unreliable transport protocol, 
  931. such as UDP. 
  932.  
  933. If the "connection" is in a healthy state, the agent responds with a RESPONSE 
  934. packet with SNMP_ERROR_DPI_noError.  If the "connection" is not in a healthy 
  935. state, the agent may respond with a RESPONSE packet with an error indication, 
  936. but the agent might not react at all.  In this situation, you would timeout 
  937. while waiting for a response. 
  938.  
  939.  
  940. ΓòÉΓòÉΓòÉ 3.13. Multithreading Programming Considerations ΓòÉΓòÉΓòÉ
  941.  
  942. The DPI Version 2.0 DLL for OS/2 (DPI20DLL.DLL file) has been compiled with the 
  943. /Gm+ compiler flag.  This enables it to be used by both single and 
  944. multithreaded subagents.  However, even a single threaded subagent must be 
  945. compiled with the /Gm+ compiler flag. 
  946.  
  947. There are several static buffers in the DPI code.  For compatibility reasons, 
  948. that cannot be changed.  Real multithread support will probably mean several 
  949. potentially incompatible changes to the DPI 2.0 API. 
  950.  
  951. Use a Locking Mechanism 
  952.  
  953. If your subagent will be a multithreaded process, then you must always use some 
  954. locking mechanism of your own around the use of the static buffers.  Otherwise, 
  955. one thread maybe writing into the static buffer while another is writing into 
  956. the same buffer at the same time. There are two static buffers.  One buffer is 
  957. for building the serialized DPI packet before sending it out and the other 
  958. buffer is for receiving incoming DPI packets. 
  959.  
  960. Basically, all DPI functions that return a pointer to an unsigned char are the 
  961. DPI functions that write into the static buffer to create a serialized DPI 
  962. packet: 
  963.  
  964. mkDPIAreYouThere()
  965. mkDPIopen()
  966. mkDPIregister()
  967. mkDPIunregister()
  968. mkDPItrap()
  969. mkDPIresponse()
  970. mkDPIpacket()
  971. mkDPIclose ()
  972.  
  973. After you have called the DPIsend_packet_to_agent() function for the buffer, 
  974. which is pointed to by the pointer returned by one of the above functions, it 
  975. is free to use again. 
  976.  
  977. There is one function that reads the static input buffer: 
  978.  
  979. pDPIpacket()
  980.  
  981. The input buffer gets filled by the DPIawait_packet_from_agent() function.  You 
  982. get a pointer to the static input buffer upon return from the await.  The 
  983. pDPIpacket() function parses the static input buffer and returns a pointer to 
  984. dynamically allocated memory. Therefore, after the pDPIparse() call, the buffer 
  985. is available for use again. 
  986.  
  987. The current situation is such that if multiple threads are waiting at the same 
  988. time and for different handles, there is the risk that two incoming DPI packets 
  989. will overlay each other. 
  990.  
  991. If multiple threads are waiting for the same handle, when data arrives both 
  992. threads come out of the wait.  If one of them issues another wait before the 
  993. other one is finished parsing the input buffer, the buffer may get overlaid by 
  994. a new packet before the second one gets a chance to parse the packet. 
  995.  
  996. The DPI internal handle structures and control blocks used by the underlying 
  997. code to send and receive data to and from the agent are also static data areas. 
  998. You must make sure that you use your own locking mechanism around the functions 
  999. that add, change, or delete data in those static structures.  The functions 
  1000. that change those internal static structures are: 
  1001.  
  1002. DPIconnect_to_agentTCP()
  1003. DPIconnect_to_agentSHM()
  1004. DPIconnect_to_agentUDP()
  1005. DPIdisconnect_from_agent()
  1006.  
  1007. The other functions that access those static structures which must be assured 
  1008. that the structure is not being changed while they are referencing it during 
  1009. their execution are: 
  1010.  
  1011. DPIawait_packet_from_agent()
  1012. DPIsend_packet_to_agent()
  1013. DPIget_fd_for_handle()
  1014.  
  1015. While the last 3 functions can be executed concurrently in different threads, 
  1016. you must ensure that no other thread is adding or deleting handles during this 
  1017. process. 
  1018.  
  1019.  
  1020. ΓòÉΓòÉΓòÉ 4. Basic DPI API Functions ΓòÉΓòÉΓòÉ
  1021.  
  1022. This section describes each of the basic DPI functions that are available to 
  1023. the DPI subagent programmer. 
  1024.  
  1025. Topics 
  1026.  
  1027.       The DPIdebug() Function 
  1028.       The DPI_PACKET_LEN() Macro 
  1029.       The fDPIparse() Function 
  1030.       The fDPIset() Function 
  1031.       The mkDPIAreYouThere() Function 
  1032.       The mkDPIclose() Function 
  1033.       The mkDPIopen() Function 
  1034.       The mkDPIregister() Function 
  1035.       The mkDPIresponse() Function 
  1036.       The mkDPIset() Function 
  1037.       The mkDPItrap() Function 
  1038.       The mkDPIunregister() Function 
  1039.       The pDPIpacket() Function 
  1040.  
  1041.  
  1042. ΓòÉΓòÉΓòÉ 4.1. The DPIdebug() Function ΓòÉΓòÉΓòÉ
  1043.  
  1044. Syntax 
  1045.  
  1046. #include <snmp_dpi.h>
  1047.  
  1048. void DPIdebug(int level);
  1049.  
  1050. Parameters 
  1051.  
  1052.  level 
  1053.    If this value is zero, tracing is turned off.  If it has any other value, 
  1054.    tracing is turned on at the specified level.  The higher the value, the more 
  1055.    detail.  A higher level includes all lower levels of tracing.  Currently 
  1056.    there are two levels of detail: 
  1057.  
  1058.    1       Display packet creation and parsing. 
  1059.  
  1060.    2       Display hex dump of incoming and outgoing DPI packets. 
  1061.  
  1062.  Description 
  1063.  
  1064.  The DPIdebug() function turns DPI internal debugging/tracing on or off. 
  1065.  
  1066.  Examples 
  1067.  
  1068.     #include <snmp_dpi.h>
  1069.  
  1070.     DPIdebug(2);
  1071.  
  1072.  Related Information 
  1073.  
  1074.       The snmp_dpi.h Include File 
  1075.  
  1076.  
  1077. ΓòÉΓòÉΓòÉ 4.2. The DPI_PACKET_LEN() Macro ΓòÉΓòÉΓòÉ
  1078.  
  1079. Syntax 
  1080.  
  1081. #include <snmp_dpi.h>
  1082.  
  1083. int DPI_PACKET_LEN(unsigned char *packet_p)
  1084.  
  1085. Parameters 
  1086.  
  1087.  packet_p 
  1088.    A pointer to a serialized DPI packet. 
  1089.  
  1090.  Return Values 
  1091.  
  1092.       An integer representing the total DPI packet length. 
  1093.  
  1094.  Description 
  1095.  
  1096.  The DPI_PACKET_LEN macro generates C-code that returns an integer representing 
  1097.  the length of a DPI packet.  It uses the first two octets in network byte 
  1098.  order of the packet to calculate the length. 
  1099.  
  1100.  Examples 
  1101.  
  1102.     #include <snmp_dpi.h>
  1103.     unsigned char *pack_p;
  1104.     int            length;
  1105.  
  1106.     pack_p = mkDPIclose(SNMP_CLOSE_goingDown);
  1107.     if (pack_p) {
  1108.        length = DPI_PACKET_LEN(pack_p);
  1109.        /* send packet to agent or subagent */
  1110.     } /* endif */
  1111.  
  1112.  
  1113. ΓòÉΓòÉΓòÉ 4.3. The fDPIparse() Function ΓòÉΓòÉΓòÉ
  1114.  
  1115. Syntax 
  1116.  
  1117. #include <snmp_dpi.h>
  1118.  
  1119. void fDPIparse(snmp_dpi_hdr *hdr_p);
  1120.  
  1121. Parameters 
  1122.  
  1123.  hdr_p 
  1124.    A pointer to the parse tree.  The parse tree is represented by an 
  1125.    snmp_dpi_hdr structure. 
  1126.  
  1127.  Description 
  1128.  
  1129.  The fDPIparse() function frees a parse tree that was previously created by a 
  1130.  call to pDPIpacket().  The parse tree may have been created in other ways too. 
  1131.  After calling fDPIparse(), no further references to the parse tree can be 
  1132.  made. 
  1133.  
  1134.  A complete or partial DPI parse tree is also implicitly freed by call to a DPI 
  1135.  function that serializes a parse tree into a DPI packet. The section that 
  1136.  describes each function tells you if this is the case.  An example of such a 
  1137.  function is mkDPIresponse(). 
  1138.  
  1139.  Examples 
  1140.  
  1141.     #include <snmp_dpi.h>
  1142.     snmp_dpi_hdr  *hdr_p;
  1143.     unsigned char *pack_p;         /* assume pack_p points to  */
  1144.                                    /* incoming DPI packet      */
  1145.     hdr_p = pDPIpacket(pack_p);
  1146.  
  1147.     /* handle the packet and when done do the following */
  1148.     if (hdr_p) fDPIparse(hdr_p);
  1149.  
  1150.  Related Information 
  1151.  
  1152.       The snmp_dpi_hdr Structure 
  1153.       The pDPIpacket() Function 
  1154.       The snmp_dpi.h Include File 
  1155.  
  1156.  
  1157. ΓòÉΓòÉΓòÉ 4.4. The fDPIset() Function ΓòÉΓòÉΓòÉ
  1158.  
  1159. Syntax 
  1160.  
  1161. #include <snmp_dpi.h>
  1162.  
  1163. void fDPIset(snmp_dpi_set_packet *packet_p);
  1164.  
  1165. Parameters 
  1166.  
  1167.  packet_p 
  1168.    A pointer to the first snmp_dpi_set_packet structure in a chain of such 
  1169.    structures. 
  1170.  
  1171.  Description 
  1172.  
  1173.  The fDPIset() function is typically used if you must free a chain of one or 
  1174.  more snmp_dpi_set_packet structures.  This may be the case if you are in the 
  1175.  middle of preparing a chain of such structures for a DPI RESPONSE packet, but 
  1176.  then run into an error before you can actually make the response. 
  1177.  
  1178.  If you get to the point where you make a DPI response packet to which you pass 
  1179.  the chain of snmp_dpi_set_packet structures, then the mkDPIresponse() function 
  1180.  will free the chain of snmp_dpi_set_packet structures. 
  1181.  
  1182.  Examples 
  1183.  
  1184.   #include <snmp_dpi.h>
  1185.   unsigned char       *pack_p;
  1186.   snmp_dpi_hdr        *hdr_p;
  1187.   snmp_dpi_set_packet *set_p, *first_p;
  1188.   long int             num1 = 0, num2 = 0;
  1189.  
  1190.   hdr_p = pDPIpacket(pack_p);              /* assume pack_p     */
  1191.   /* analyze packet and assume all OK */   /* points to the     */
  1192.   /* now prepare response; 2 varBinds */   /* incoming packet   */
  1193.  
  1194.   set_p = mkDPIset(snmp_dpi_NULL_p,        /* create first one  */
  1195.                "1.3.6.1.2.3.4.5.","1.0",   /* OID=1, instance=0 */
  1196.                SNMP_TYPE_Integer32,
  1197.                sizeof(num1), &num1);
  1198.   if (set_p) {                             /* if success, then  */
  1199.      first_p = set_p;                      /* save ptr to first */
  1200.      set_p   = mkDPIset(set_p,             /* chain next one    */
  1201.                  "1.3.6.1.2.3.4.5.","1.1", /* OID=1, instance=1 */
  1202.                  SNMP_TYPE_Integer32,
  1203.                  sizeof(num2), &num2);
  1204.      if (set_p) {                          /* success 2nd one   */
  1205.         pack_p = mkDPIresponse(hdr_p,      /* make response     */
  1206.                       SNMP_ERROR_noError,  /* It will also free */
  1207.                       0L, first_p);        /* the set_p tree    */
  1208.         /* send DPI response to agent */
  1209.      } else {                              /* 2nd mkDPIset fail */
  1210.         fDPIset(first_p);                  /* must free chain   */
  1211.      } /* endif */
  1212.   } /* endif */
  1213.  
  1214.  Related Information 
  1215.  
  1216.       The fDPIparse() Function 
  1217.       The snmp_dpi_set_packet Structure 
  1218.       The mkDPIresponse() Function 
  1219.  
  1220.  
  1221. ΓòÉΓòÉΓòÉ 4.5. The mkDPIAreYouThere() Function ΓòÉΓòÉΓòÉ
  1222.  
  1223. Syntax 
  1224.  
  1225. #include <snmp_dpi.h>
  1226.  
  1227. unsigned char *mkDPIAreYouThere(void);
  1228.  
  1229. Parameters 
  1230.  
  1231.    None. 
  1232.  
  1233.  Return Values 
  1234.  
  1235.       If successful, a pointer to a static DPI packet buffer is returned.  The 
  1236.       first two bytes of the buffer in network byte order contain the length of 
  1237.       the remaining packet.  The macro DPI_PACKET_LEN can be used to calculate 
  1238.       the total length of the DPI packet. 
  1239.  
  1240.       If failure, a NULL pointer is returned. 
  1241.  
  1242.  Note:  The static buffer for the DPI packet is shared by other mkDPIxxxx() 
  1243.  functions that create a serialized DPI packet. 
  1244.  
  1245.  Description 
  1246.  
  1247.  The mkDPIAreYouThere() function creates a serialized DPI ARE_YOU_THERE packet 
  1248.  that can be sent to the DPI peer, which is normally the agent. 
  1249.  
  1250.  A subagent connected via TCP probably does not need this function because, 
  1251.  normally when the agent breaks the "connection", you will receive an EOF on 
  1252.  the file descriptor.  For unreliable "connections", like over UDP, this 
  1253.  function may be useful to periodically poll the agent and verify that it still 
  1254.  knows about the subagent. 
  1255.  
  1256.  If your "connection" to the agent is still healthy, the agent will send a DPI 
  1257.  RESPONSE with SNMP_ERROR_DPI_noError in the error code field and zero in the 
  1258.  error index field.  The RESPONSE will have no varBind data.  If your 
  1259.  "connection" is not healthy, the agent may send a response with an error 
  1260.  indication, or may just not send a response at all. 
  1261.  
  1262.  Examples 
  1263.  
  1264.     #include <snmp_dpi.h>
  1265.     unsigned char *pack_p;
  1266.  
  1267.     pack_p = mkDPIAreYouThere();
  1268.     if (pack_p) {
  1269.        /* send the packet to the agent */
  1270.     } /* endif */
  1271.     /* wait for response with DPIawait_packet_from_agent() */
  1272.     /* normally the response should come back pretty quickly, */
  1273.     /* but it depends on the load of the agent */
  1274.  
  1275.  Related Information 
  1276.  
  1277.       The snmp_dpi_resp_packet Structure 
  1278.       The DPIawait_packet_from_agent() Function 
  1279.  
  1280.  
  1281.  
  1282. ΓòÉΓòÉΓòÉ 4.6. The mkDPIclose() Function ΓòÉΓòÉΓòÉ
  1283.  
  1284. Syntax 
  1285.  
  1286. #include <snmp_dpi.h>
  1287.  
  1288. unsigned char *mkDPIclose(char reason_code);
  1289.  
  1290. Parameters 
  1291.  
  1292.  reason_code 
  1293.    The reason for closing the DPI connection.  See DPI CLOSE Reason Codes for a 
  1294.    list of valid reason codes. 
  1295.  
  1296.  Return Values 
  1297.  
  1298.       If successful, a pointer to a static DPI packet buffer is returned.  The 
  1299.       first two bytes of the buffer in network byte order contain the length of 
  1300.       the remaining packet.  The macro DPI_PACKET_LEN can be used to calculate 
  1301.       the total length of the DPI packet. 
  1302.  
  1303.       If failure, a NULL pointer is returned. 
  1304.  
  1305.  Note:  The static buffer for the DPI packet is shared by other mkDPIxxxx() 
  1306.  functions that create a serialized DPI packet. 
  1307.  
  1308.  Description 
  1309.  
  1310.  The mkDPIclose() function creates a serialized DPI CLOSE packet that can be 
  1311.  sent to the DPI peer.  As a result of sending the packet, the DPI connection 
  1312.  will be closed. 
  1313.  
  1314.  Sending a DPI CLOSE packet to the agent implies an automatic DPI UNREGISTER 
  1315.  for all registered sub-trees on the connection being closed. 
  1316.  
  1317.  Examples 
  1318.  
  1319.     #include <snmp_dpi.h>
  1320.     unsigned char *pack_p;
  1321.  
  1322.     pack_p = mkDPIclose(SNMP_CLOSE_goingDown);
  1323.     if (pack_p) {
  1324.        /* send the packet to the agent */
  1325.     } /* endif */
  1326.  
  1327.  Related Information 
  1328.  
  1329.       The snmp_dpi_close_packet Structure 
  1330.       DPI CLOSE Reason Codes 
  1331.  
  1332.  
  1333. ΓòÉΓòÉΓòÉ 4.7. The mkDPIopen() Function ΓòÉΓòÉΓòÉ
  1334.  
  1335. Syntax 
  1336.  
  1337. #include <snmp_dpi.h>
  1338.  
  1339. unsigned char *mkDPIopen(       /* Make a DPI open packet     */
  1340.   char          *oid_p,         /* subagent Identifier (OID) */
  1341.   char          *description_p, /* subagent descriptive name */
  1342.   unsigned long  timeout,       /* requested default timeout  */
  1343.   unsigned long  max_varBinds,  /* max varBinds per DPI ndle  */
  1344.   char           character_set, /* selected character set     */
  1345.   #define DPI_NATIVE_CSET  0    /*   0 = native character set */
  1346.   #define DPI_ASCII_CSET   1    /*   1 = ASCII  character set */
  1347.  
  1348.   unsigned long  password_len,  /* length of password (if any)*/
  1349.   unsigned char *password_p);   /* ptr to password (if any)   */
  1350.  
  1351. Parameters 
  1352.  
  1353.  oid_p 
  1354.    A pointer to a NULL terminated character string representing the OBJECT 
  1355.    IDENTIFIER which uniquely identifies the subagent. 
  1356.  
  1357.  description_p 
  1358.    A pointer to a NULL terminated character string, which is a descriptive name 
  1359.    for the subagent.  This can be any DisplayString, which basically is an 
  1360.    octet string containing only characters from the ASCII NVT set. 
  1361.  
  1362.  timeout 
  1363.    The requested timeout for this subagent.  An agent often has a limit for 
  1364.    this value and it will use that limit if this value is larger.  A timeout of 
  1365.    zero has a special meaning in the sense that the agent will use its own 
  1366.    default timeout value. 
  1367.  
  1368.  max_varBinds 
  1369.    The maximum number of varBinds per DPI packet that the subagent is prepared 
  1370.    to handle.  It must be a positive number or zero.  If a value greater than 1 
  1371.    is specified, the agent will try to combine as many varBinds which belong to 
  1372.    the same sub-tree per DPI packet as possible up to this value. 
  1373.  
  1374.    If a value of zero is specified, the agent will try to combine up to as many 
  1375.    varBinds as are present in the SNMP packet and belong to the same sub-tree. 
  1376.    For example, a value of zero means no limit. 
  1377.  
  1378.  character_set 
  1379.    The character set that you want to use for string-based data fields in the 
  1380.    DPI packets and structures.  The choices are: 
  1381.  
  1382.    DPI_NATIVE_CSET            Specifies that you want to use the native 
  1383.                               character set of the platform on which the agent 
  1384.                               that you connect to is running. 
  1385.  
  1386.    DPI_ASCII_CSET             Specifies that you want to use the ASCII 
  1387.                               character set.  The agent will translate between 
  1388.                               ASCII and the native character set as required. 
  1389.  
  1390.    See Character Set Selection for more information. 
  1391.  
  1392.  password_len 
  1393.    The length in octets of an optional password.  It depends on the agent 
  1394.    implementation if a password is needed.  If not, a zero length may be 
  1395.    specified. 
  1396.  
  1397.  password_p 
  1398.    A pointer to an octet string representing the password for this subagent.  A 
  1399.    password may include any character value, including the NULL character.  If 
  1400.    the password_len is zero, this can be a NULL pointer. 
  1401.  
  1402.  Return Values 
  1403.  
  1404.       If successful, a pointer to a static DPI packet buffer is returned.  The 
  1405.       first two bytes of the buffer in network byte order contain the length of 
  1406.       the remaining packet.  The macro DPI_PACKET_LEN can be used to calculate 
  1407.       the total length of the DPI packet. 
  1408.  
  1409.       If failure, a NULL pointer is returned. 
  1410.  
  1411.  Note:  The static buffer for the DPI packet is shared by other mkDPIxxxx() 
  1412.  functions that create a serialized DPI packet. 
  1413.  
  1414.  Description 
  1415.  
  1416.  The mkDPIopen() function creates a serialized DPI OPEN packet that can then be 
  1417.  sent to the DPI peer which is a DPI capable SNMP agent. 
  1418.  
  1419.  Normally you will want to use the native character set, which is the easiest 
  1420.  for the subagent programmer.  However, if the agent and subagent each run on 
  1421.  their own platform and those platforms use different native character sets, 
  1422.  you must select the ASCII character set, so that you both know exactly how to 
  1423.  represent string-based data that is being send back and forth. 
  1424.  
  1425.  Currently you do not need to specify a password to connect to the OS/2 SNMP 
  1426.  agent.  Therefore, you can pass a length of zero and a NULL pointer for the 
  1427.  password. 
  1428.  
  1429.  Examples 
  1430.  
  1431.     #include <snmp_dpi.h>
  1432.     unsigned char *pack_p;
  1433.  
  1434.     pack_p = mkDPIopen("1.3.6.1.2.3.4.5",
  1435.                   "Sample DPI subagent"
  1436.                   0L,2L, DPI_NATIVE_CSET, /* max 2 varBinds */
  1437.                   0,(char *)0);
  1438.     if (pack_p) {
  1439.        /* send packet to the agent */
  1440.     } /* endif */
  1441.  
  1442.  Related Information 
  1443.  
  1444.       Character Set Selection 
  1445.  
  1446.  
  1447. ΓòÉΓòÉΓòÉ 4.8. The mkDPIregister() Function ΓòÉΓòÉΓòÉ
  1448.  
  1449. Syntax 
  1450.  
  1451. #include <snmp_dpi.h>
  1452.  
  1453. unsigned char  *mkDPIregister(  /* Make a DPI register packet */
  1454.   unsigned short   timeout,     /* in seconds (16-bit)        */
  1455.   long int         priority,    /* requested priority         */
  1456.   char            *group_p,     /* ptr to group ID (sub-tree) */
  1457.   char             bulk_select);/* Bulk selection (GETBULK)   */
  1458.   #define DPI_BULK_NO   0       /*  map GETBULK into GETNEXTs */
  1459.   #define DPI_BULK_YES  1       /*  pass GETBULK to subagent */
  1460.  
  1461. Parameters 
  1462.  
  1463.  timeout 
  1464.    The requested timeout in seconds.  An agent often has a limit for this value 
  1465.    and it will use that limit if this value is larger.  The value zero has 
  1466.    special meaning in the sense that it tells the agent to use the timeout 
  1467.    value that was specified in the DPI OPEN packet. 
  1468.  
  1469.  priority 
  1470.    The requested priority.  This field may contain any of these values: 
  1471.  
  1472.    -1        Requests the best available priority. 
  1473.  
  1474.     0        Requests a better priority than the highest priority currently 
  1475.              registered.  Use this value to obtain the SNMP DPI Version 1 
  1476.              behavior. 
  1477.  
  1478.    nnn       Any positive value.  You will receive that priority if available, 
  1479.              otherwise the next best priority that is available. 
  1480.  
  1481.  group_p 
  1482.    A pointer to a NULL terminated character string that represents the sub-tree 
  1483.    to be registered.  This group ID must have a trailing dot. 
  1484.  
  1485.  bulk_select 
  1486.    Specifies if you want the agent to pass GETBULK on to the subagent or to map 
  1487.    them into multiple GETNEXT requests.  The choices are: 
  1488.  
  1489.    DPI_BULK_NO           Do not pass any GETBULK requests, but instead map a 
  1490.                          GETBULK request into multiple GETNEXT requests. 
  1491.  
  1492.    DPI_BULK_YES          Do pass a GETBULK request to the subagent. 
  1493.  
  1494.  Return Values 
  1495.  
  1496.       If successful, a pointer to a static DPI packet buffer is returned.  The 
  1497.       first two bytes of the buffer in network byte order contain the length of 
  1498.       the remaining packet.  The macro DPI_PACKET_LEN can be used to calculate 
  1499.       the total length of the DPI packet. 
  1500.  
  1501.       If failure, a NULL pointer is returned. 
  1502.  
  1503.  Note:  The static buffer for the DPI packet is shared by other mkDPIxxxx() 
  1504.  functions that create a serialized DPI packet. 
  1505.  
  1506.  Description 
  1507.  
  1508.  The mkDPIregister() function creates a serialized DPI REGISTER packet that can 
  1509.  then be sent to the DPI peer which is a DPI capable SNMP agent. 
  1510.  
  1511.  The bulk_select can be used to ask the agent to map an SNMP GETBULK request 
  1512.  into multiple GETNEXT requests.  This makes it easier for the DPI subagent 
  1513.  programmer because GETBULK processing doesn't need implementing. 
  1514.  
  1515.  However, if one expects that a single GETBULK might improve the performance a 
  1516.  lot, one can tell the agent to pass such requests.  This might be the case if 
  1517.  one expects a GETBULK to arrive often for a table for which one needs to do a 
  1518.  kernel dive.  Using GETBULK, one might be able to do just one dive instead of 
  1519.  many.  Although one could anticipate the dive with a GETNEXT also, and 
  1520.  therefore obtain and cache the table upon the first GETNEXT request. 
  1521.  
  1522.  According to the DPI 2.0 RFC, not all agents need to support DPI_BULK_YES. 
  1523.  These agents will return an appropriate error code in the DPI RESPONSE though 
  1524.  if such is the case. 
  1525.  
  1526.  Normally the SNMP agent sends a DPI RESPONSE packet back.  This packet 
  1527.  identifies if the register was successful or not. 
  1528.  
  1529.  Examples 
  1530.  
  1531.     #include <snmp_dpi.h>
  1532.     unsigned char *pack_p;
  1533.  
  1534.     pack_p = mkDPIregister(0,0L,"1.3.6.1.2.3.4.5."
  1535.                            DPI_BULK_NO);
  1536.     if (pack_p) {
  1537.        /* send packet to agent and await response */
  1538.     } /* endif */
  1539.  
  1540.  Related Information 
  1541.  
  1542.       The snmp_dpi_resp_packet Structure 
  1543.  
  1544.  
  1545. ΓòÉΓòÉΓòÉ 4.9. The mkDPIresponse() Function ΓòÉΓòÉΓòÉ
  1546.  
  1547. Syntax 
  1548.  
  1549. #include <snmp_dpi.h>
  1550.  
  1551. unsigned char    *mkDPIresponse( /* Make a DPI response packet*/
  1552.   snmp_dpi_hdr     *hdr_p,       /* ptr to packet to respnd to*/
  1553.   long int          error_code,  /* error code: SNMP_ERROR_xxx*/
  1554.   long int          error_index, /* index to varBind in error */
  1555.   snmp_dpi_set_packet *packet_p);/* ptr to varBinds, a chain  */
  1556.                                  /* of dpi_set_packets        */
  1557.  
  1558. Parameters 
  1559.  
  1560.  hdr_p 
  1561.    A pointer to the parse tree of the DPI request to which this DPI packet will 
  1562.    be the response.  The function uses this parse tree to copy the packet_id 
  1563.    and the DPI version and release, so that the DPI packet is correctly 
  1564.    formatted as a response. 
  1565.  
  1566.  error_code 
  1567.    The error code. 
  1568.  
  1569.    See DPI RESPONSE Error Codes for a list of valid codes. 
  1570.  
  1571.  error_index 
  1572.    Specifies the first varBind in error.  Counting starts at 1 for the first 
  1573.    varBind.  This field should be zero if there is no error. 
  1574.  
  1575.  packet_p 
  1576.    A pointer to a chain of snmp_dpi_set_packet structures.  This partial parse 
  1577.    tree will be freed by the mkDPIresponse() function.  So upon return you 
  1578.    cannot reference it anymore.  Pass a NULL pointer if there are no varBinds 
  1579.    to be returned. 
  1580.  
  1581.  Return Values 
  1582.  
  1583.       If successful, a pointer to a static DPI packet buffer is returned.  The 
  1584.       first two bytes of the buffer in network byte order contain the length of 
  1585.       the remaining packet.  The macro DPI_PACKET_LEN can be used to calculate 
  1586.       the total length of the DPI packet. 
  1587.  
  1588.       If failure, a NULL pointer is returned. 
  1589.  
  1590.  Note:  The static buffer for the DPI packet is shared by other mkDPIxxxx() 
  1591.  functions that create a serialized DPI packet. 
  1592.  
  1593.  Description 
  1594.  
  1595.  The mkDPIresponse() function is used at the subagent side to prepare a DPI 
  1596.  RESPONSE packet to a GET, GETNEXT, GETBULK, SET, COMMIT or UNDO request.  The 
  1597.  resulting packet can be sent to the DPI peer, which is normally a DPI capable 
  1598.  SNMP agent. 
  1599.  
  1600.  Examples 
  1601.  
  1602.     #include <snmp_dpi.h>
  1603.     unsigned char       *pack_p;
  1604.     snmp_dpi_hdr        *hdr_p;
  1605.     snmp_dpi_set_packet *set_p;
  1606.     long int             num;
  1607.  
  1608.     hdr_p = pDPIpacket(pack_p);     /* parse incoming packet */
  1609.                                     /* assume it's in pack_p */
  1610.     if (hdr_p) {
  1611.        /* analyze packet, assume GET, no error */
  1612.        set_p = mkDPIset(snmp_dpi_set_packet_NULL_p,
  1613.                         "1.3.6.1.2.3.4.5.", "1.0",
  1614.                         SNMP_TYPE_Integer32,
  1615.                         sizeof(num), &num);
  1616.        if (set_p) {
  1617.           pack_p = mkDPIresponse(hdr_p,
  1618.                         SNMP_ERROR_noError, 0L, set_p);
  1619.           if (pack_p) {
  1620.              /* send packet to subagent */
  1621.           } /* endif */
  1622.        } /* endif */
  1623.     } /* endif */
  1624.  
  1625.  The mkDPIresponse() function is used at the agent side to prepare a DPI 
  1626.  RESPONSE packet to an OPEN, REGISTER or UNREGISTER request.  In the case of a 
  1627.  RESPONSE to a REGISTER request and if there is no error, the actually assigned 
  1628.  priority must be passed in the error_index parameter.  The resulting packet 
  1629.  can be sent to the DPI peer, which is normally a subagent. 
  1630.  
  1631.  Examples 
  1632.  
  1633.     #include <snmp_dpi.h>
  1634.     unsigned char       *pack_p;
  1635.     snmp_dpi_hdr        *hdr_p;
  1636.     long int             priority;
  1637.  
  1638.     hdr_p = pDPIpacket(pack_p);     /* parse incoming packet */
  1639.                                     /* assume it's in pack_p */
  1640.     if (hdr_p) {
  1641.        /* analyze packet, assume REGISTER and OK */
  1642.        pack_p = mkDPIresponse(hdr_p,
  1643.                      SNMP_ERROR_DPI_noError,
  1644.                      priority,
  1645.                      snmp_dpi_set_packet_NULL_p);
  1646.        if (pack_p) {
  1647.           /* send packet to subagent */
  1648.        } /* endif */
  1649.     } /* endif */
  1650.  
  1651.  Related Information 
  1652.  
  1653.       The pDPIpacket() Function 
  1654.       The snmp_dpi_hdr Structure 
  1655.       The snmp_dpi_next_packet Structure 
  1656.  
  1657.  
  1658. ΓòÉΓòÉΓòÉ 4.10. The mkDPIset() Function ΓòÉΓòÉΓòÉ
  1659.  
  1660. Syntax 
  1661.  
  1662. #include <snmp_dpi.h>
  1663.  
  1664. snmp_dpi_set_packet *mkDPIset(    /* Make DPI set packet tree */
  1665.   snmp_dpi_set_packet *packet_p,  /* ptr to SET structure     */
  1666.   char                *group_p,   /* ptr to group ID(sub-tree)*/
  1667.   char                *instance_p,/* ptr to instance OIDstring*/
  1668.   int                  value_type,/* value type: SNMP_TYPE_xxx*/
  1669.   int                  value_len, /* length of value          */
  1670.   void                *value_p);  /* ptr to value             */
  1671.  
  1672. Parameters 
  1673.  
  1674.  packet_p 
  1675.    A pointer to a chain of snmp_dpi_set_packet structures.  Pass a NULL pointer 
  1676.    if this is the first structure to be created. 
  1677.  
  1678.  group_p 
  1679.    A pointer to a NULL terminated character string that represents the 
  1680.    registered sub-tree that caused this GET request to be passed to this DPI 
  1681.    subagent.  The sub-tree must have a trailing dot. 
  1682.  
  1683.  instance_p 
  1684.    A pointer to a NULL terminated character string that represents the rest, 
  1685.    which is the piece following the sub-tree part, of the OBJECT IDENTIFIER of 
  1686.    the variable instance being accessed.  Use of the term instance_p here 
  1687.    should not be confused with an OBJECT instance because this string may 
  1688.    consist of a piece of the OBJECT IDENTIFIER plus the INSTANCE IDENTIFIER. 
  1689.  
  1690.  value_type 
  1691.    The type of the value. 
  1692.  
  1693.    See DPI SNMP Value Types for a list of currently defined value types. 
  1694.  
  1695.  value_len 
  1696.    This is the value that specifies the length in octets of the value pointed 
  1697.    to by the value field.  The length may be zero if the value is of type 
  1698.    SNMP_TYPE_NULL. 
  1699.  
  1700.    The maximum value is 64K -1.  However, the implementation often makes the 
  1701.    length significantly less.  The OS/2 implementation limit is 4K.  The 
  1702.    SNMP_DPI_BUFFSIZE in the snmp_dpi.h include file defines the limit for OS/2. 
  1703.  
  1704.  value_p 
  1705.    A pointer to the actual value.  This field may contain a NULL pointer if the 
  1706.    value is of implicit or explicit type SNMP_TYPE_NULL. 
  1707.  
  1708.  Return Values 
  1709.  
  1710.       If successful and a chain of one or more packets was passed in the 
  1711.       packet_p parameter, the same pointer that was passed in packet_p is 
  1712.       returned.  A new dynamically allocated structure has then been added to 
  1713.       the end of that chain of snmp_dpi_get_packet structures. 
  1714.  
  1715.       If successful and a NULL pointer was passed in the packet_p parameter, a 
  1716.       pointer to a new dynamically allocated structure is returned. 
  1717.  
  1718.       If failure, a NULL pointer is returned. 
  1719.  
  1720.  Description 
  1721.  
  1722.  The mkDPIset() function is used at the subagent side to prepare a chain of one 
  1723.  or more snmp_dpi_set_packet structures.  This chain is used to create a DPI 
  1724.  RESPONSE packet by a call to mkDPIresponse() which can be sent to the DPI 
  1725.  peer, which is normally a DPI capable SNMP agent. 
  1726.  
  1727.  The chain of snmp_dpi_set_packet structures can also be used to create a DPI 
  1728.  TRAP packet that includes varBinds as explained in The mkDPItrap() Function. 
  1729.  
  1730.  For the value_len, the maximum value is 64K -1.  However, the implementation 
  1731.  often makes the length significantly less.  For example the SNMP PDU size may 
  1732.  be limited to 484 bytes at the SNMP manager or agent side.  In this case, the 
  1733.  total response packet cannot exceed 484 bytes, so a value_len is limited by 
  1734.  that.  You can send the DPI packet to the agent, but the manager will never 
  1735.  see it. 
  1736.  
  1737.  Examples 
  1738.  
  1739.     #include <snmp_dpi.h>
  1740.     unsigned char       *pack_p;
  1741.     snmp_dpi_hdr        *hdr_p;
  1742.     snmp_dpi_set_packet *set_p;
  1743.     long int             num;
  1744.  
  1745.     hdr_p = pDPIpacket(pack_p)      /* parse incoming packet */
  1746.                                     /* assume it's in pack_p */
  1747.     if (hdr_p) {
  1748.        /* analyze packet, assume GET, no error */
  1749.        set_p = mkDPIset(snmp_dpi_set_packet_NULL_p,
  1750.                         "1.3.6.1.2.3.4.5.", "1.0",
  1751.                         SNMP_TYPE_Integer32,
  1752.                         sizeof(num), &num);
  1753.        if (set_p) {
  1754.           pack_p = mkDPIresponse(hdr_p,
  1755.                         SNMP_ERROR_noError,
  1756.                         0L, set_p);
  1757.           if (pack_p)
  1758.              /* send packet to subagent */
  1759.           } /* endif */
  1760.        } /* endif */
  1761.     } /* endif */
  1762.  
  1763.  The mkDPIset() function is used at the agent side to prepare a chain of one or 
  1764.  more snmp_dpi_set_packet structures.  This chain is normally anchored in an 
  1765.  snmp_dpi_hdr structure that has its packet_type field set to SNMP_DPI_SET, 
  1766.  SNMP_DPI_COMMIT or SNMP_DPI_UNDO.  When all varBinds have been prepared into 
  1767.  snmp_dpi_set_packet structures, a call can be made to mkDPIpacket() which will 
  1768.  serialize the DPI parse tree into a DPI packet that can be sent to the DPI 
  1769.  peer, which is normally a subagent. 
  1770.  
  1771.  Examples 
  1772.  
  1773.     #include <snmp_dpi.h>
  1774.     unsigned char       *pack_p;
  1775.     snmp_dpi_hdr        *hdr_p;
  1776.     long int             num;
  1777.  
  1778.     hdr_p = mkDPIhdr(SNMP_DPI_SET);
  1779.     if (hdr_p) {
  1780.        hdr_p->data_u.set_p =
  1781.               mkDPIset(snmp_dpi_set_packet_NULL_p,
  1782.                        "1.3.6.1.2.3.4.5.", "1.0",
  1783.                        SNMP_TYPE_Integer32,
  1784.                        sizeof(num), &num);
  1785.        if (hdr_p->data_u.set_p) {
  1786.           pack_p = mkDPIpacket(hdr_p);
  1787.           if (pack_p)
  1788.              /* send packet to subagent */
  1789.           } /* endif */
  1790.        } /* endif */
  1791.     } /* endif */
  1792.  
  1793.  If you must chain many snmp_dpi_set_packet structures, be sure to note that 
  1794.  the packets are chained only by forward pointers.  It is recommended that you 
  1795.  use the last structure in the existing chain as the packet_p parameter.  Then, 
  1796.  the underlying code does not have to scan through a possibly long chain of 
  1797.  structures in order to chain the new structure at the end. 
  1798.  
  1799.  In the next example let's assume that we want to chain 20 snmp_dpi_set_packet 
  1800.  structures as a response to a GETBULK. 
  1801.  
  1802.  Examples 
  1803.  
  1804.     #include <snmp_dpi.h>
  1805.     unsigned char       *pack_p;
  1806.     snmp_dpi_hdr        *hdr_p;
  1807.     snmp_dpi_set_packet *first_p;
  1808.     snmp_dpi_set_packet *set_p;
  1809.     long int             num[20];
  1810.     int                  i;
  1811.  
  1812.     hdr_p = pDPIpacket(pack_p);    /* parse incoming packet    */
  1813.                                    /* assume it's in pack_p    */
  1814.     if (hdr_p) {
  1815.        /* analyze packet, assume GETBULK, no error. In this    */
  1816.        /* example we do not check max_repetitions as we should */
  1817.        set_p   = snmp_dpi_set_packet_NULL_p;
  1818.        first_p = snmp_dpi_set_packet_NULL_p;
  1819.        for (i=0; i<20; i++) {
  1820.            char instance[5];
  1821.  
  1822.            sprintf(instance, "%1.%d", i+1);
  1823.            set_p = mkDPIset(set_p,
  1824.                         "1.3.6.1.2.3.4.5.", instance,
  1825.                         SNMP_TYPE_Integer32,
  1826.                         sizeof(num), &num[i]);
  1827.            if (set_p) {
  1828.               if (first_p) continue; /* OK, iterate for loop  */
  1829.               first_p = set_p;       /* remember first one    */
  1830.            } else if (first_p) {     /* failed to mkDPIset    */
  1831.               fDPIset(first_p)       /* free allocated memory */
  1832.               first_p = snmp_dpi_set_packet_NULL_p; /* reset  */
  1833.            } /* endif */
  1834.        } /* endfor */
  1835.        if (first_p) {
  1836.           pack_p = mkDPIresponse(hdr_p,
  1837.                         SNMP_ERROR_noError,
  1838.                         0L, first_p);
  1839.           if (pack_p)
  1840.              /* send packet to subagent */
  1841.           } /* endif */
  1842.        } /* endif */
  1843.     } /* endif */
  1844.  
  1845.  Related Information 
  1846.  
  1847.       The pDPIpacket() Function 
  1848.       The mkDPIresponse() Function 
  1849.       The mkDPItrap() Function 
  1850.       The snmp_dpi_hdr Structure 
  1851.       The snmp_dpi_set_packet Structure 
  1852.       DPI SNMP Value Types 
  1853.       Value Representation 
  1854.  
  1855.  
  1856. ΓòÉΓòÉΓòÉ 4.11. The mkDPItrap() Function ΓòÉΓòÉΓòÉ
  1857.  
  1858. Syntax 
  1859.  
  1860. #include <snmp_dpi.h>
  1861.  
  1862. unsigned char      *mkDPItrap(   /* Make a DPI trap packet    */
  1863.   long int            generic,   /* generic traptype  (32 bit)*/
  1864.   long int            specific,  /* specific traptype (32 bit)*/
  1865.   snmp_dpi_set_packet *packet_p, /* ptr to varBinds, a chain  */
  1866.                                  /* of dpi_set_packets        */
  1867.   char           *enterprise_p); /* ptr to enterprise OID     */
  1868.  
  1869. Parameters 
  1870.  
  1871.  generic 
  1872.    The generic trap type.  The range of this value is 0-6, where 6, which is 
  1873.    enterprise specific, is the type that is probably used most by DPI subagent 
  1874.    programmers.  The values 0-5 are well defined standard SNMP traps. 
  1875.  
  1876.  specific 
  1877.    The enterprise specific trap type.  This can be any value that is valid for 
  1878.    the MIB sub-trees that the subagent implements. 
  1879.  
  1880.  packet_p 
  1881.    A pointer to a chain of snmp_dpi_set_structures, representing the varBinds 
  1882.    to be passed with the trap.  This partial parse tree will be freed by the 
  1883.    mkDPItrap() function so you cannot reference it anymore upon completion of 
  1884.    the call.  A NULL pointer means that there are no varBinds to be included in 
  1885.    the trap. 
  1886.  
  1887.  enterprise_p 
  1888.    A pointer to a NULL terminated character string representing the enterprise 
  1889.    ID (OBJECT IDENTIFIER) for which this trap is defined.  A NULL pointer can 
  1890.    be used.  In this case, the subagent Identifier, as passed in the DPI OPEN 
  1891.    packet, will be used when the agent receives the DPI TRAP packet. 
  1892.  
  1893.  Return Values 
  1894.  
  1895.       If successful, a pointer to a static DPI packet buffer is returned.  The 
  1896.       first two bytes of the buffer in network byte order contain the length of 
  1897.       the remaining packet.  The macro DPI_PACKET_LEN can be used to calculate 
  1898.       the total length of the DPI packet. 
  1899.  
  1900.       If failure, a NULL pointer is returned. 
  1901.  
  1902.  Note:  The static buffer for the DPI packet is shared by other mkDPIxxxx() 
  1903.  functions that create a serialized DPI packet. 
  1904.  
  1905.  Description 
  1906.  
  1907.  The mkDPItrap() function is used at the subagent side to prepare a DPI TRAP 
  1908.  packet.  The resulting packet can be sent to the DPI peer, which is normally a 
  1909.  DPI capable SNMP agent. 
  1910.  
  1911.  Examples 
  1912.  
  1913.     #include <snmp_dpi.h>
  1914.     unsigned char       *pack_p;
  1915.     snmp_dpi_set_packet *set_p;
  1916.     long int             num;
  1917.  
  1918.     set_p = mkDPIset(snmp_dpi_set_packet_NULL_p,
  1919.                      "1.3.6.1.2.3.4.5.", "1.0",
  1920.                      SNMP_TYPE_Integer32,
  1921.                      sizeof(num), &num);
  1922.     if (set_p) {
  1923.        pack_p = mkDPItrap(6,1,set_p, (char *)0);
  1924.        if (pack_p) {
  1925.           /* send packet to subagent */
  1926.        } /* endif */
  1927.     } /* endif */
  1928.  
  1929.  Related Information 
  1930.  
  1931.       The fDPIset() Function 
  1932.  
  1933.  
  1934. ΓòÉΓòÉΓòÉ 4.12. The mkDPIunregister() Function ΓòÉΓòÉΓòÉ
  1935.  
  1936. Syntax 
  1937.  
  1938. #include <snmp_dpi.h>
  1939.  
  1940. unsigned char *mkDPIunregister( /* Make DPI unregister packet */
  1941.   char           reason_code;   /* unregister reason code     */
  1942.   char          *group_p);      /* ptr to group ID (sub-tree) */
  1943.  
  1944. Parameters 
  1945.  
  1946.  reason_code 
  1947.    The reason for the unregister. 
  1948.  
  1949.    See DPI UNREGISTER Reason Codes for a list of the currently defined reason 
  1950.    codes. 
  1951.  
  1952.  group_p 
  1953.    A pointer to a NULL terminated character string that represents the sub-tree 
  1954.    to be unregistered.  The sub-tree must have a trailing dot. 
  1955.  
  1956.  Return Values 
  1957.  
  1958.       If successful, a pointer to a static DPI packet buffer is returned.  The 
  1959.       first two bytes of the buffer in network byte order contain the length of 
  1960.       the remaining packet.  The macro DPI_PACKET_LEN can be used to calculate 
  1961.       the total length of the DPI packet. 
  1962.  
  1963.       If failure, a NULL pointer is returned. 
  1964.  
  1965.  Note:  The static buffer for the DPI packet is shared by other mkDPIxxxx() 
  1966.  functions that create a serialized DPI packet. 
  1967.  
  1968.  Description 
  1969.  
  1970.  The mkDPIunregister() function creates a serialized DPI UNREGISTER packet that 
  1971.  can be sent to the DPI peer, which is a DPI capable SNMP agent or subagent. 
  1972.  
  1973.  Normally, the SNMP peer then sends a DPI RESPONSE packet back.  This packet 
  1974.  identifies if the unregister was successful or not. 
  1975.  
  1976.  Examples 
  1977.  
  1978.     #include <snmp_dpi.h>
  1979.     unsigned char *pack_p;
  1980.  
  1981.     pack_p = mkDPIunregister(
  1982.                   SNMP_UNREGISTER_goingDown,
  1983.                   "1.3.6.1.2.3.4.5.");
  1984.     if (pack_p) {
  1985.        /* send packet to agent or subagent and await response */
  1986.     } /* endif */
  1987.  
  1988.  Related Information 
  1989.  
  1990.       The snmp_dpi_ureg_packet Structure 
  1991.  
  1992.  
  1993. ΓòÉΓòÉΓòÉ 4.13. The pDPIpacket() Function ΓòÉΓòÉΓòÉ
  1994.  
  1995. Syntax 
  1996.  
  1997. #include <snmp_dpi.h>
  1998.  
  1999. snmp_dpi_hdr *pDPIpacket(unsigned char *packet_p);
  2000.  
  2001. Parameters 
  2002.  
  2003.  packet_p 
  2004.    A pointer to a serialized DPI packet. 
  2005.  
  2006.  Return Values 
  2007.  
  2008.       If successful, a pointer to a DPI parse tree (snmp_dpi_hdr) is returned. 
  2009.       Memory for the parse tree has been dynamically allocated, and it is the 
  2010.       callers responsibility to free it when no longer needed. You can use the 
  2011.       fDPIparse() function to free the parse tree. 
  2012.  
  2013.       If failure, a NULL pointer is returned. 
  2014.  
  2015.  Description 
  2016.  
  2017.  The pDPIpacket() function parses the buffer pointed to by the packet_p 
  2018.  parameter.  It ensures that the buffer contains a valid DPI packet and that 
  2019.  the packet is for a DPI version and release that is supported by the DPI 
  2020.  functions in use. 
  2021.  
  2022.  Examples 
  2023.  
  2024.     #include <snmp_dpi.h>
  2025.     unsigned char       *pack_p;
  2026.     snmp_dpi_hdr        *hdr_p;
  2027.  
  2028.     hdr_p = pDPIpacket(pack_p);       /* parse incoming packet */
  2029.                                       /* assume it's in pack_p */
  2030.     if (hdr_p) {
  2031.        /* analyze packet, and handle it */
  2032.     }
  2033.  
  2034.  Related Information 
  2035.  
  2036.       The snmp_dpi_hdr Structure 
  2037.       The snmp_dpi.h Include File 
  2038.       The fDPIparse() Function 
  2039.  
  2040.  
  2041. ΓòÉΓòÉΓòÉ 5. Transport-Related DPI API Functions ΓòÉΓòÉΓòÉ
  2042.  
  2043. This section describes each of the DPI transport-related functions that are 
  2044. available to the DPI subagent programmer.  These functions try to hide any 
  2045. platform specific issues for the DPI subagent programmer so that the subagent 
  2046. can be made as portable as possible.  If you need detailed control for sending 
  2047. and awaiting DPI packets, you may have to do some of the transport-related code 
  2048. yourself. 
  2049.  
  2050. The transport-related functions are basically the same for any platform, except 
  2051. for the initial call to setup a connection.  OS/2 currently supports the TCP/IP 
  2052. transport type. 
  2053.  
  2054. Topics 
  2055.  
  2056.       The DPIawait_packet_from_agent() Function 
  2057.       The DPIconnect_to_agent_SHM() Function 
  2058.       The DPIconnect_to_agent_TCP() Function 
  2059.       The DPIdisconnect_from_agent() Function 
  2060.       The DPIget_fd_for_handle() Function 
  2061.       The DPIsend_packet_to_agent() Function 
  2062.       The lookup_host() Function 
  2063.       The query_DPI_port() Function 
  2064.  
  2065.  
  2066. ΓòÉΓòÉΓòÉ 5.1. The DPIawait_packet_from_agent() Function ΓòÉΓòÉΓòÉ
  2067.  
  2068. Syntax 
  2069.  
  2070. #include <snmp_dpi.h>
  2071.  
  2072. int DPIawait_packet_from_agent(    /* await a DPI packet      */
  2073.   int                   handle,    /* on this connection      */
  2074.   int                   timeout,   /* timeout in seconds      */
  2075.   unsigned char       **message_p, /* receives ptr to data    */
  2076.   unsigned long        *length);   /* receives length of data */
  2077.  
  2078. Parameters 
  2079.  
  2080.  handle 
  2081.    A handle as obtained with a DPIconnect_to_agent_xxxx() call. 
  2082.  
  2083.  timeout 
  2084.    A timeout value in seconds.  There are two special values: 
  2085.  
  2086.    -1           Causes the function to wait forever until a packet arrives. 
  2087.  
  2088.     0           Means that the function will only check if a packet is waiting. 
  2089.                 If not, an immediate return is made.  If there is a packet, it 
  2090.                 will be returned. 
  2091.  
  2092.  message_p 
  2093.    The address of a pointer that will receive the address of a static DPI 
  2094.    packet buffer or, if there is no packet, a NULL pointer. 
  2095.  
  2096.  length 
  2097.    The address of an unsigned long integer that will receive the length of the 
  2098.    received DPI packet or, if there is no packet, a zero value. 
  2099.  
  2100.  Return Values 
  2101.  
  2102.       If successful, a zero (DPI_RC_noError) is returned.  The buffer pointer 
  2103.       and length of the caller will be set to point to the received DPI packet 
  2104.       and to the length of that packet. 
  2105.  
  2106.       If failure, a negative integer is returned.  It indicates the kind of 
  2107.       error that occurred.  See Return Codes from DPI Transport-Related 
  2108.       Functions for a list of possible error codes. 
  2109.  
  2110.  Description 
  2111.  
  2112.  The DPIawait_packet_from_agent() function is used at the subagent side to 
  2113.  await a DPI packet from the DPI capable SNMP agent.  The programmer can 
  2114.  specify how long to wait. 
  2115.  
  2116.  Examples 
  2117.  
  2118.     #include <snmp_dpi.h>
  2119.     int                  handle;
  2120.     unsigned char       *pack_p;
  2121.     unsigned long        length;
  2122.  
  2123.     handle = DPIconnect_to_agent_TCP("localhost", "public");
  2124.     if (handle < 0) {
  2125.        printf("Error %d from connect\n",handle);
  2126.        exit(1);
  2127.     } /* endif */
  2128.     /* do useful stuff */
  2129.     rc = DPIawait_packet_from_agent(handle, -1,
  2130.                               &pack_p, &length);
  2131.     if (rc) {
  2132.        printf("Error %d from await packet\n");
  2133.        exit(1);
  2134.     } /* endif */
  2135.     /* handle the packet */
  2136.  
  2137.  Related Information 
  2138.  
  2139.       The DPIconnect_to_agent_TCP() Function 
  2140.  
  2141.  
  2142. ΓòÉΓòÉΓòÉ 5.2. The DPIconnect_to_agent_SHM() Function ΓòÉΓòÉΓòÉ
  2143.  
  2144. Syntax 
  2145.  
  2146. #inlcude <snmp_dpi.h>
  2147.  
  2148. int  DPIconnect_to_agent_SHM(  /* Connect to DPI Shared Mem  */
  2149.         int          queue_id);/* target (agent) queue id    */
  2150.  
  2151. Parameters 
  2152.  
  2153.  queu_id 
  2154.    A queue_id known by the agent.  The value is a fixed queueid.  It must 
  2155.    always be 1. 
  2156.  
  2157.  Return Values 
  2158.  
  2159.       If successful, a positive integer that represents the connection is 
  2160.       returned.  It is to be used as a handle in subsequent calls to DPI 
  2161.       transport-related functions. 
  2162.  
  2163.       If failure, a negative integer is returned.  It indicates the kind of 
  2164.       error that occurred.  See Return Codes from DPI Transport-Related 
  2165.       Functions for a list of possible error codes. 
  2166.  
  2167.  Description 
  2168.  
  2169.  The DPIconnect_to_agent_SHM() function is used at the subagent side to setup a 
  2170.  connection (via SHared Memory) to the DPI capable SNMP agent. 
  2171.  
  2172.  Examples 
  2173.  
  2174.   #include <snmp_dpi.h>
  2175.   int                  handle;
  2176.  
  2177.   handle = DPIconnect_to_agent_SHM(1);
  2178.   if (handle < 0) {
  2179.      printf("Error %d from connect\n",handle);
  2180.      exit(1);
  2181.   }          /* endif */
  2182.  
  2183.  Related Information 
  2184.  
  2185.       Return Codes from DPI Transport-Related Functions 
  2186.       The DPIconnect_to_agent_TCP() Function 
  2187.  
  2188.  
  2189. ΓòÉΓòÉΓòÉ 5.3. The DPIconnect_to_agent_TCP() Function ΓòÉΓòÉΓòÉ
  2190.  
  2191. Syntax 
  2192.  
  2193. #include <snmp_dpi.h>
  2194.  
  2195. int DPIconnect_to_agent_TCP(    /* Connect to DPI TCP port    */
  2196.   char          *hostname_p,    /* target hostname/IP address */
  2197.   char          *community_p);  /* community name             */
  2198.  
  2199. Parameters 
  2200.  
  2201.  hostname_p 
  2202.    A pointer to a NULL terminated character string representing the host name 
  2203.    or IP address in dot notation of the host where the DPI capable SNMP agent 
  2204.    is running. 
  2205.  
  2206.  community_p 
  2207.    A pointer to a NULL terminated character string representing the community 
  2208.    name that is required to obtain the dpiPort from the SNMP agent via an SNMP 
  2209.    GET request. 
  2210.  
  2211.  Return Values 
  2212.  
  2213.       If successful, a positive integer that represents the connection is 
  2214.       returned.  It is to be used as a handle in subsequent calls to DPI 
  2215.       transport-related functions. 
  2216.  
  2217.       If failure, a negative integer is returned.  It indicates the kind of 
  2218.       error that occurred.  See Return Codes from DPI Transport-Related 
  2219.       Functions for a list of possible error codes. 
  2220.  
  2221.  Description 
  2222.  
  2223.  The DPIconnect_to_agent_TCP() function is used at the subagent side to setup a 
  2224.  TCP connection to the DPI capable SNMP agent. 
  2225.  
  2226.  Examples 
  2227.  
  2228.     #include <snmp_dpi.h>
  2229.     int                  handle;
  2230.  
  2231.     handle = DPIconnect_to_agent_TCP("localhost", "loopback");
  2232.     if (handle < 0) {
  2233.        printf("Error %d from connect\n",handle);
  2234.        exit(1);
  2235.     } /* endif */
  2236.  
  2237.  Related Information 
  2238.  
  2239.       Return Codes from DPI Transport-Related Functions 
  2240.       The DPIconnect_to_agent_SHM() Function 
  2241.  
  2242.  
  2243. ΓòÉΓòÉΓòÉ 5.4. The DPIdisconnect_from_agent() Function ΓòÉΓòÉΓòÉ
  2244.  
  2245. Syntax 
  2246.  
  2247. #include <snmp_dpi.h>
  2248.  
  2249. void DPIdisconnect_from_agent(  /* disconnect from DPI (agent)*/
  2250.   int                  handle); /* close this connection      */
  2251.  
  2252. Parameters 
  2253.  
  2254.  handle 
  2255.    A handle as obtained with a DPIconnect_to_agent_xxxx() call. 
  2256.  
  2257.  Return Values 
  2258.  
  2259.       If successful, a positive integer that represents the connection is 
  2260.       returned.  It is to be used as a handle in subsequent calls to DPI 
  2261.       transport-related functions. 
  2262.  
  2263.       If failure, a negative integer is returned.  It indicates the kind of 
  2264.       error that occurred.  See Return Codes from DPI Transport-Related 
  2265.       Functions for a list of possible error codes. 
  2266.  
  2267.  Description 
  2268.  
  2269.  The DPIdisconnect_from_agent() function is used at the subagent side to 
  2270.  terminate a connection to the DPI capable SNMP agent. 
  2271.  
  2272.  Examples 
  2273.  
  2274.     #include <snmp_dpi.h>
  2275.     int                  handle;
  2276.  
  2277.     handle = DPIconnect_to_agent_TCP("localhost", "loopback");
  2278.     if (handle < 0) {
  2279.        printf("Error %d from connect\n",handle);
  2280.        exit(1);
  2281.     } /* endif */
  2282.     /* do useful stuff */
  2283.     DPIdisconnect_from_agent(handle);
  2284.  
  2285.  Related Information 
  2286.  
  2287.       The DPIconnect_to_agent_TCP() Function 
  2288.  
  2289.  
  2290. ΓòÉΓòÉΓòÉ 5.5. The DPIget_fd_for_handle() Function ΓòÉΓòÉΓòÉ
  2291.  
  2292. Syntax 
  2293.  
  2294. #include <snmp_dpi.h>
  2295.  
  2296. int DPIget_fd_for_handle(       /* get the file descriptor    */
  2297.   int            handle);       /* for this handle            */
  2298.  
  2299. Parameters 
  2300.  
  2301.  handle 
  2302.    A handle that was obtained with a DPIconnect_to_agent_TCP() call. 
  2303.  
  2304.  Return Values 
  2305.  
  2306.       If successful, a positive integer representing the file descriptor 
  2307.       associated with the specified handle. 
  2308.  
  2309.       If failure, a negative integer is returned.  It indicates the error that 
  2310.       occurred.  See Return Codes from DPI Transport-Related Functions for a 
  2311.       list of possible error codes. 
  2312.  
  2313.  Description 
  2314.  
  2315.  The DPIget_fd_for_handle function is used to obtain the file descriptor for 
  2316.  the handle, which was obtained with a DPIconnect_to_agent_TCP() call. 
  2317.  
  2318.  The DPI subagent programmer would use this function to not only wait for DPI 
  2319.  requests, but possibly for other TCP/IP events.  The programmer may want to do 
  2320.  their own select and include for the file descriptor of the DPI connections. 
  2321.  
  2322.  Examples 
  2323.  
  2324.   #include <snmp_dpi.h>
  2325.   #include /* other include files for BSD sockets and such */
  2326.   int                  handle;
  2327.   int                  fd;
  2328.  
  2329.   handle = DPIconnect_to_agentTCP("localhost","public");
  2330.   if (handle < 0) {
  2331.      printf("Error %d from connect\n",handle);
  2332.      exit(1);
  2333.   }
  2334.   fd = DPIget_fd_for_handle(handle);
  2335.   if (fd <0) {
  2336.      printf("Error %d from get_fd\n",fd);
  2337.      exit(1);
  2338.   }
  2339.  
  2340.  Related Information 
  2341.  
  2342.       The DPIconnect_to_agent_TCP() Function 
  2343.  
  2344.  
  2345. ΓòÉΓòÉΓòÉ 5.6. The DPIsend_packet_to_agent() Function ΓòÉΓòÉΓòÉ
  2346.  
  2347. Syntax 
  2348.  
  2349. #include <snmp_dpi.h>
  2350.  
  2351. int DPIsend_packet_to_agent(       /* send  a DPI packet      */
  2352.   int                   handle,    /* on this connection      */
  2353.   unsigned char        *message_p, /* ptr to the packet data  */
  2354.   unsigned long         length);   /* length of the packet    */
  2355.  
  2356. Parameters 
  2357.  
  2358.  handle 
  2359.    A handle as obtained with a DPIconnect_to_agent_xxxx() call. 
  2360.  
  2361.  message_p 
  2362.    A pointer to the buffer containing the DPI packet to be sent. 
  2363.  
  2364.  length 
  2365.    The length of the DPI packet to be sent.  The DPI_PACKET_LEN macro is a 
  2366.    useful macro to calculate the length. 
  2367.  
  2368.  Return Values 
  2369.  
  2370.       If successful, a zero (DPI_RC_noError) is returned. 
  2371.  
  2372.       If failure, a negative integer is returned.  It indicates the kind of 
  2373.       error that occurred.  See Return Codes from DPI Transport-Related 
  2374.       Functions for a list of possible error codes. 
  2375.  
  2376.  Description 
  2377.  
  2378.  The DPIsend_packet_to_agent() function is used at the subagent side to send a 
  2379.  DPI packet to the DPI capable SNMP agent. 
  2380.  
  2381.  Examples 
  2382.  
  2383.     #include <snmp_dpi.h>
  2384.     int                  handle;
  2385.     unsigned char       *pack_p;
  2386.  
  2387.     handle = DPIconnect_to_agent_TCP("localhost", "public");
  2388.     if (handle < 0) {
  2389.        printf("Error %d from connect\n",handle);
  2390.        exit(1);
  2391.     } /* endif */
  2392.     pack_p = mkDPIopen("1.3.6.1.2.3.4.5",
  2393.                   "Sample DPI subagent"
  2394.                   0L,2L,,DPI_NATIVE_CSET,
  2395.                   0,(char *)0);
  2396.     if (pack_p) {
  2397.        rc = DPIsend_packet_to_agent(handle,pack_p,
  2398.                            DPI_PACKET_LEN(pack_p));
  2399.        if (rc) {
  2400.           printf("Error %d from await packet\n");
  2401.           exit(1);
  2402.        } /* endif */
  2403.     } else {
  2404.        printf("Can't make DPI OPEN packet\n");
  2405.        exit(1);
  2406.     } /* endif */
  2407.     /* await the response */
  2408.  
  2409.  Related Information 
  2410.  
  2411.       The DPIconnect_to_agent_TCP() Function 
  2412.       The DPI_PACKET_LEN() Macro 
  2413.       The mkDPIopen() Function 
  2414.  
  2415.  
  2416. ΓòÉΓòÉΓòÉ 5.7. The lookup_host() Function ΓòÉΓòÉΓòÉ
  2417.  
  2418. Syntax 
  2419.  
  2420. #include <snmp_dpi.h>
  2421.  
  2422. unsigned long    lookup_host(   /* find IP address in network */
  2423.   char            *hostname_p); /* byte order for this host   */
  2424.  
  2425. Parameters 
  2426.  
  2427.  hostname_p 
  2428.    A pointer to a NULL terminated character string representing the host name 
  2429.    or IP address in dot notation of the host where the DPI capable SNMP agent 
  2430.    is running. 
  2431.  
  2432.  Return Values 
  2433.  
  2434.       If successful, the IP address is returned in network byte order, so it is 
  2435.       ready to be used in a sockaddr_in structure. 
  2436.  
  2437.       If failure, a value of 0 is returned. 
  2438.  
  2439.  Description 
  2440.  
  2441.  The lookup_host() function is used to obtain the IP address in network byte 
  2442.  order of a host or IP address in dot notation. 
  2443.  
  2444.  The DPI subagent programmer only needs to use this function to code the 
  2445.  connection setup and send or await the packet.  The programmer then obtains 
  2446.  the DPI port number, finds the IP address of the agent with the lookup_host() 
  2447.  function and then sets up a socket for communication. 
  2448.  
  2449.  This function is implicitly executed by the DPIconnect_to_agent_TCP() 
  2450.  function, which is the function that the DPI subagent programmer would 
  2451.  normally use.  So the lookup_host() function is normally not used by the DPI 
  2452.  subagent programmer. 
  2453.  
  2454.  Examples 
  2455.  
  2456.   #include <snmp_dpi.h>
  2457.   #include /* other include files for BSD sockets and such */
  2458.   int                  handle;
  2459.   unsigned char       *pack_p;
  2460.   long int             dpi_port;
  2461.   int                  fd;
  2462.   struct sockaddr_in   s,t;              /* source and target   */
  2463.  
  2464.   dpi_port = query_DPI_port("localhost", /* get DPI port number */
  2465.                     "public",            /* for TCP, local host */
  2466.                     dpiPortForTCP);
  2467.   if (dpi_port < 0) exit(1);             /* error if negative   */
  2468.  
  2469.   host_addr = lookup_host("localhost");  /* find target IP addr */
  2470.   if (host_addr == 0) exit(1);           /* unknown, that's it  */
  2471.  
  2472.   fd = socket(AF_INET,SOCK_STREAM,0);    /* create a TCP socket */
  2473.   if (fd < 0) exit(1);                   /* failure to do so    */
  2474.  
  2475.   memset(&s,0,sizeof(s));
  2476.   s.sin_family      = AF_INET;           /* set AF_INET family  */
  2477.   s.sin_port        = 0;                 /* give us any port,   */
  2478.   s.sin_addr.s_addr = htonl(INADDR_ANY); /* any local IPaddress */
  2479.  
  2480.   rc = bind(fd,(struct sockaddr *)s,     /* bind our socket(fd) */
  2481.             sizeof(s_sock));             /* defined in s socket */
  2482.   if (rc < 0) exit(1);                   /* failure, so exit    */
  2483.  
  2484.   memset(&d,0,sizeof(d));
  2485.   d.sin_family      = AF_INET;           /* set AF_INET family  */
  2486.   d.sin_port        = htons(dpi_port);   /* set requested port  */
  2487.   d.sin_addr.s_addr = host_addr;         /* destination IP addr */
  2488.                                          /* network byte order  */
  2489.   rc = connect(fd,(struct sockaddr *)d,  /* connect to target   */
  2490.                sizeof(d));               /* based on d sock     */
  2491.   if (rc < 0) exit(1);                   /* failed, exit        */
  2492.   /* now we have a socket on which to send/receive DPI packets  */
  2493.  
  2494.  Related Information 
  2495.  
  2496.       The query_DPI_port() Function 
  2497.       The DPIconnect_to_agent_TCP() Function 
  2498.  
  2499.  
  2500. ΓòÉΓòÉΓòÉ 5.8. The query_DPI_port() Function ΓòÉΓòÉΓòÉ
  2501.  
  2502. Syntax 
  2503.  
  2504. #include <snmp_dpi.h>
  2505.  
  2506. long int query_DPI_port(        /* Query (GET) SNMP_DPI port  */
  2507.   char          *hostname_p,    /* target hostname/IPaddress  */
  2508.   char          *community_p,   /* communityname for GET      */
  2509.   int            porttype);     /* port type, one of:         */
  2510.                                 /*   dpiPortForTCP            */
  2511.                                 /*   dpiPortForUDP            */
  2512.  
  2513. Parameters 
  2514.  
  2515.  hostname_p 
  2516.    A pointer to a NULL terminated character string representing the host name 
  2517.    or IP address in dot notation of the host where the DPI capable SNMP agent 
  2518.    is running. 
  2519.  
  2520.  community_p 
  2521.    A pointer to a NULL terminated character string representing the community 
  2522.    name that is required to obtain the dpiPort from the SNMP agent via an SNMP 
  2523.    GET request. 
  2524.  
  2525.  porttype 
  2526.    The dpiPort object for a specific port type that you want to obtain. 
  2527.    Currently there are two types:  one for a TCP port and one for a UDP port. 
  2528.    The snmp_dpi.h include file has two #define statements for these DPI port 
  2529.    types: 
  2530.  
  2531.         #define dpiPortForTCP    1
  2532.         #define dpiPortForUDP    2
  2533.  
  2534.    At this time, the dpiPORTForUDP port type is not supported.  If you use it, 
  2535.    the return value is set to -1, which indicates a failure. 
  2536.  
  2537.  Return Values 
  2538.  
  2539.       If successful, the DPI port number for the specified protocol, TCP or 
  2540.       UDP, is returned. 
  2541.  
  2542.       If failure, a value of -1 is returned. 
  2543.  
  2544.  Description 
  2545.  
  2546.  The query_DPI_port function is used to obtain the port number on which the DPI 
  2547.  capable SNMP agent at the specified host is listening for connections (TCP) or 
  2548.  packets (UDP). 
  2549.  
  2550.  The DPI subagent programmer only needs to use this function to code the 
  2551.  connection setup and send or await the packet.  The programmer then obtains 
  2552.  the DPI port number, finds the IP address of the agent with the lookup_host() 
  2553.  function and then sets up a socket for communication. 
  2554.  
  2555.  This function is implicitly executed by the DPIconnect_to_agent_TCP() 
  2556.  function, which is the function that the DPI subagent programmer would 
  2557.  normally use.  So the query_DPI_port() function is normally not used by the 
  2558.  DPI subagent programmer. 
  2559.  
  2560.  Examples 
  2561.  
  2562.   #include <snmp_dpi.h>
  2563.   #include /* other include files for BSD sockets and such */
  2564.   int                  handle;
  2565.   unsigned char       *pack_p;
  2566.   long int             dpi_port;
  2567.   int                  fd;
  2568.   struct sockaddr_in   s,t;              /* source and target   */
  2569.  
  2570.   dpi_port = query_DPI_port("localhost", /* get DPI port number */
  2571.                     "public",            /* for TCP, local host */
  2572.                     dpiPortForTCP);
  2573.   if (dpi_port < 0) exit(1);             /* error if negative   */
  2574.  
  2575.   host_addr = lookup_host("localhost");  /* find target IP addr */
  2576.   if (host_addr == 0) exit(1);           /* unknown, that's it  */
  2577.  
  2578.   fd = socket(AF_INET,SOCK_STREAM,0);    /* create a TCP socket */
  2579.   if (fd < 0) exit(1);                   /* failure to do so    */
  2580.  
  2581.   memset(&s,0,sizeof(s));
  2582.   s.sin_family      = AF_INET;           /* set AF_INET family  */
  2583.   s.sin_port        = 0;                 /* give us any port,   */
  2584.   s.sin_addr.s_addr = htonl(INADDR_ANY); /* any local IPaddress */
  2585.  
  2586.   rc = bind(fd,(struct sockaddr *)s,     /* bind our socket(fd) */
  2587.             sizeof(s_sock));             /* defined in s socket */
  2588.   if (rc < 0) exit(1);                   /* failure, so exit    */
  2589.  
  2590.   memset(&d,0,sizeof(d));
  2591.   d.sin_family      = AF_INET;           /* set AF_INET family  */
  2592.   d.sin_port        = htons(dpi_port);   /* set requested port  */
  2593.   d.sin_addr.s_addr = host_addr;         /* destination IP addr */
  2594.                                          /* network byte order  */
  2595.   rc = connect(fd,(struct sockaddr *)d,  /* connect to target   */
  2596.                sizeof(d));               /* based on d sock     */
  2597.   if (rc < 0) exit(1);                   /* failed, exit        */
  2598.   /* now we have a socket on which to send/receive DPI packets  */
  2599.  
  2600.  Related Information 
  2601.  
  2602.       The lookup_host() Function 
  2603.       The DPIconnect_to_agent_TCP() Function 
  2604.  
  2605.  
  2606. ΓòÉΓòÉΓòÉ 6. DPI Structures ΓòÉΓòÉΓòÉ
  2607.  
  2608. This section describes each data structure that is used in the SNMP DPI API. 
  2609.  
  2610. Topics 
  2611.  
  2612.       The snmp_dpi_bulk_packet Structure 
  2613.       The snmp_dpi_close_packet Structure 
  2614.       The snmp_dpi_get_packet Structure 
  2615.       The snmp_dpi_next_packet Structure 
  2616.       The snmp_dpi_hdr Structure 
  2617.       The snmp_dpi_resp_packet Structure 
  2618.       The snmp_dpi_set_packet Structure 
  2619.       The snmp_dpi_ureg_packet Structure 
  2620.       The snmp_dpi_u64 Structure 
  2621.  
  2622.  
  2623. ΓòÉΓòÉΓòÉ 6.1. The snmp_dpi_bulk_packet Structure ΓòÉΓòÉΓòÉ
  2624.  
  2625. Structure Definition 
  2626.  
  2627. struct dpi_bulk_packet {
  2628.   long int          non_repeaters;   /* count of non-repeaters*/
  2629.   long int          max_repetitions; /* max repeaters         */
  2630.   struct dpi_next_packet *varBind_p; /* ptr to varBinds, chain*/
  2631.                                      /* of dpi_next_packets   */
  2632. };
  2633. typedef struct dpi_bulk_packet       snmp_dpi_bulk_packet;
  2634. #define snmp_dpi_bulk_packet_NULL_p  ((snmp_dpi_bulk_packet *)0)
  2635.  
  2636. Note:  This structure is supported only in SNMP Version 2. 
  2637.  
  2638. Structure Members 
  2639.  
  2640.  non_repeaters 
  2641.    The number of varBinds in the chain of dpi_next_packet structures that are 
  2642.    to be treated as a single GETNEXT. 
  2643.  
  2644.  max_repetitions 
  2645.    The maximum number of repetitions for the remaining set of varBinds in 
  2646.    dpi_next_packet structures treated as a single GETNEXT. 
  2647.  
  2648.  varBind_p 
  2649.    The pointer to the first varBind in the chain of dpi_next_packet structures. 
  2650.  
  2651.  Description 
  2652.  
  2653.  The snmp_dpi_bulk_packet structure represents a parse tree for a DPI GETBULK 
  2654.  packet. 
  2655.  
  2656.  At the subagent side, the snmp_dpi_bulk_packet structure is normally created 
  2657.  as a result of a call to pDPIpacket().  This is the case if the DPI packet is 
  2658.  of type SNMP_DPI_GETBULK.  The snmp_dpi_hdr structure then contains a pointer 
  2659.  to an snmp_dpi_bulk_packet structure, which in turn has a pointer to a chain 
  2660.  of one or more snmp_dpi_next_packet structures. 
  2661.  
  2662.  The DPI subagent programmer uses this structure to find out which variables 
  2663.  instances are to be returned in a DPI RESPONSE. 
  2664.  
  2665.  Related Information 
  2666.  
  2667.       The pDPIpacket() Function 
  2668.       The snmp_dpi_hdr Structure 
  2669.       The snmp_dpi_next_packet Structure 
  2670.  
  2671.  
  2672. ΓòÉΓòÉΓòÉ 6.2. The snmp_dpi_close_packet Structure ΓòÉΓòÉΓòÉ
  2673.  
  2674. Structure Definition 
  2675.  
  2676. struct dpi_close_packet {
  2677.   char               reason_code;    /* reason for closing    */
  2678. };
  2679. typedef struct dpi_close_packet      snmp_dpi_close_packet;
  2680. #define snmp_dpi_close_packet_NULL_p ((snmp_dpi_close_packet*)0)
  2681.  
  2682. Structure Members 
  2683.  
  2684.  reason_code 
  2685.    The reason for the close. 
  2686.  
  2687.    See DPI CLOSE Reason Codes for a list of valid reason codes. 
  2688.  
  2689.  Description 
  2690.  
  2691.  The snmp_dpi_close_packet structure represents a parse tree for a DPI CLOSE 
  2692.  packet. 
  2693.  
  2694.  The snmp_dpi_close_packet structure may be created as a result of a call to 
  2695.  pDPIpacket().  This is the case if the DPI packet is of type SNMP_DPI_CLOSE. 
  2696.  The snmp_dpi_hdr structure then contains a pointer to a snmp_dpi_close_packet 
  2697.  structure. 
  2698.  
  2699.  An snmp_dpi_close_packet_structure is also created as a result of a 
  2700.  mkDPIclose() call, but the programmer never sees the structure since 
  2701.  mkDPIclose() immediately creates a serialized DPI packet from it and then 
  2702.  frees the structure. 
  2703.  
  2704.  It is recommended that DPI subagent programmer uses mkDPIclose() to create a 
  2705.  DPI CLOSE packet. 
  2706.  
  2707.  Related Information 
  2708.  
  2709.       The pDPIpacket() Function 
  2710.       The mkDPIclose() Function 
  2711.       The snmp_dpi_hdr Structure 
  2712.  
  2713.  
  2714. ΓòÉΓòÉΓòÉ 6.3. The snmp_dpi_get_packet Structure ΓòÉΓòÉΓòÉ
  2715.  
  2716. Structure Definition 
  2717.  
  2718. struct dpi_get_packet {
  2719.   char                  *object_p;   /* ptr to OID string     */
  2720.   char                  *group_p;    /* ptr to sub-tree(group)*/
  2721.   char                  *instance_p; /* ptr to rest of OID    */
  2722.   struct dpi_get_packet *next_p;     /* ptr to next in chain  */
  2723. };
  2724. typedef struct dpi_get_packet        snmp_dpi_get_packet;
  2725. #define snmp_dpi_get_packet_NULL_p   ((snmp_dpi_get_packet *)0)
  2726.  
  2727. Structure Members 
  2728.  
  2729.  object_p 
  2730.    A pointer to a NULL terminated character string that represents the full 
  2731.    OBJECT IDENTIFIER of the variable instance that is being accessed.  It 
  2732.    basically is a concatenation of the fields group_p and instance_p.  Using 
  2733.    this field is not recommended because it is only included for DPI Version 1 
  2734.    compatibility and it maybe withdrawn in a later version. 
  2735.  
  2736.  group_p 
  2737.    A pointer to a NULL terminated character string that represents the 
  2738.    registered sub-tree that caused this GET request to be passed to this DPI 
  2739.    subagent.  The sub-tree must have a trailing dot. 
  2740.  
  2741.  instance_p 
  2742.    A pointer to a NULL terminated character string that represents the rest 
  2743.    which is the piece following the sub-tree part of the OBJECT IDENTIFIER of 
  2744.    the variable instance being accessed. 
  2745.  
  2746.    Use of the term instance_p here should not be confused with an OBJECT 
  2747.    instance because this string may consist of a piece of the OBJECT IDENTIFIER 
  2748.    plus the INSTANCE IDENTIFIER. 
  2749.  
  2750.  next_p 
  2751.    A pointer to a possible next snmp_dpi_get_packet structure.  If this next 
  2752.    field contains the NULL pointer, this is the end of the chain. 
  2753.  
  2754.  Description 
  2755.  
  2756.  The snmp_dpi_get_packet structure represents a parse tree for a DPI GET 
  2757.  packet. 
  2758.  
  2759.  At the subagent side, the snmp_dpi_get_packet structure is normally created as 
  2760.  a result of a call to pDPIpacket().  This is the case if the DPI packet is of 
  2761.  type SNMP_DPI_GET.  The snmp_dpi_hdr structure then contains a pointer to a 
  2762.  chain of one or more snmp_dpi_get_packet structures. 
  2763.  
  2764.  The DPI subagent programmer uses this structure to find out which variables 
  2765.  instances are to be returned in a DPI RESPONSE. 
  2766.  
  2767.  Related Information 
  2768.  
  2769.       The pDPIpacket() Function 
  2770.       The snmp_dpi_hdr Structure 
  2771.  
  2772.  
  2773. ΓòÉΓòÉΓòÉ 6.4. The snmp_dpi_hdr Structure ΓòÉΓòÉΓòÉ
  2774.  
  2775. Structure Definition 
  2776.  
  2777. struct snmp_dpi_hdr {
  2778.   unsigned char  proto_major;   /* always 2: SNMP_DPI_PROTOCOL*/
  2779.   unsigned char  proto_version; /* DPI version                */
  2780.   unsigned char  proto_release; /* DPI release                */
  2781.   unsigned short packet_id;     /* 16-bit, DPI packet ID      */
  2782.   unsigned char  packet_type;   /* DPI packet type            */
  2783.   union {
  2784.      snmp_dpi_reg_packet      *reg_p;
  2785.      snmp_dpi_ureg_packet     *ureg_p;
  2786.      snmp_dpi_get_packet      *get_p;
  2787.      snmp_dpi_next_packet     *next_p;
  2788.      snmp_dpi_next_packet     *bulk_p;
  2789.      snmp_dpi_set_packet      *set_p;
  2790.      snmp_dpi_resp_packet     *resp_p;
  2791.      snmp_dpi_trap_packet     *trap_p;
  2792.      snmp_dpi_open_packet     *open_p;
  2793.      snmp_dpi_close_packet    *close_p;
  2794.      unsigned char            *any_p;
  2795.   } data_u;
  2796. };
  2797. typedef struct snmp_dpi_hdr    snmp_dpi_hdr;
  2798. #define snmp_dpi_hdr_NULL_p    ((snmp_dpi_hdr *)0)
  2799.  
  2800. Structure Members 
  2801.  
  2802.  proto_major 
  2803.    The major protocol.  For SNMP DPI, it is always 2. 
  2804.  
  2805.  proto_version 
  2806.    The DPI version. 
  2807.  
  2808.  proto_release 
  2809.    The DPI release. 
  2810.  
  2811.  packet_id 
  2812.    This field contains the packet ID of the DPI packet.  When you create a 
  2813.    response to a request, the packet ID must be the same as that of the 
  2814.    request. This is taken care of if you use the mkDPIresponse() function. 
  2815.  
  2816.  packet_type 
  2817.    The type of DPI packet (parse tree) which you are dealing with. 
  2818.  
  2819.    See DPI Packet Types for a list of currently defined DPI packet types 
  2820.  
  2821.  data_u 
  2822.    A union of pointers to the different types of data structures that are 
  2823.    created based on the packet_type field.  The pointers themselves have names 
  2824.    that are self-explanatory. 
  2825.  
  2826.  The fields proto_major, proto_version, proto_release, and packet_id are 
  2827.  basically for DPI internal use.  So the DPI programmer normally does not need 
  2828.  to be concerned about them.  If you work with an unreliable DPI "connection", 
  2829.  such as UDP, you may want to use the packet_id field to ensure you are 
  2830.  handling the correct packet. 
  2831.  
  2832.  Description 
  2833.  
  2834.  The snmp_dpi_hdr structure is the anchor of a DPI parse tree.  At the subagent 
  2835.  side, the snmp_dpi_hdr structure is normally created as a result of a call to 
  2836.  pDPIpacket(). 
  2837.  
  2838.  The DPI subagent programmer uses this structure to interrogate packets. 
  2839.  Depending on the packet_type, the pointer to the chain of one or more 
  2840.  packet_type specific structures that contain the actual packet data can be 
  2841.  picked. 
  2842.  
  2843.  The storage for a DPI parse tree is always dynamically allocated. It is the 
  2844.  responsibility of the caller to free this parse tree when it is no longer 
  2845.  needed.  You can use the fDPIparse() function to do that. 
  2846.  
  2847.  Note:  Some mkDPIxxxx functions do free the parse tree that is passed to them. 
  2848.  An example is the mkDPIpacket() function. 
  2849.  
  2850.  Related Information 
  2851.  
  2852.       The fDPIparse() Function 
  2853.       The pDPIpacket() Function 
  2854.       The snmp_dpi_close_packet Structure 
  2855.       The snmp_dpi_get_packet Structure 
  2856.       The snmp_dpi_next_packet Structure 
  2857.       The snmp_dpi_bulk_packet Structure 
  2858.       The snmp_dpi_resp_packet Structure 
  2859.       The snmp_dpi_set_packet Structure 
  2860.       The snmp_dpi_ureg_packet Structure 
  2861.  
  2862.  
  2863. ΓòÉΓòÉΓòÉ 6.5. The snmp_dpi_next_packet Structure ΓòÉΓòÉΓòÉ
  2864.  
  2865. Structure Definition 
  2866.  
  2867. struct dpi_next_packet {
  2868.   char                   *object_p;  /* ptr to OID (string)   */
  2869.   char                   *group_p;   /* ptr to sub-tree(group)*/
  2870.   char                   *instance_p;/* ptr to rest of OID    */
  2871.   struct dpi_next_packet *next_p;    /* ptr to next in chain  */
  2872. };
  2873. typedef struct dpi_next_packet       snmp_dpi_next_packet;
  2874. #define snmp_dpi_next_packet_NULL_p  ((snmp_dpi_next_packet *)0)
  2875.  
  2876. Structure Members 
  2877.  
  2878.  object_p 
  2879.    A pointer to a NULL terminated character string that represents the full 
  2880.    OBJECT IDENTIFIER of the variable instance that is being accessed.  It 
  2881.    basically is a concatenation of the fields group_p and instance_p.  Using 
  2882.    this field is not recommended because it is only included for DPI Version 1 
  2883.    compatibility and it maybe withdrawn in a later version. 
  2884.  
  2885.  group_p 
  2886.    A pointer to a NULL terminated character string that represents the 
  2887.    registered sub-tree that caused this GETNEXT request to be passed to this 
  2888.    DPI subagent.  This sub-tree must have a trailing dot. 
  2889.  
  2890.  instance_p 
  2891.    A pointer to a NULL terminated character string that represents the rest 
  2892.    which is the piece following the sub-tree part of the OBJECT IDENTIFIER of 
  2893.    the variable instance being accessed. 
  2894.  
  2895.    Use of the term instance_p here should not be confused with an OBJECT 
  2896.    instance because this string may consist of a piece of the OBJECT IDENTIFIER 
  2897.    plus the INSTANCE IDENTIFIER. 
  2898.  
  2899.  next_p 
  2900.    A pointer to a possible next snmp_dpi_get_packet structure.  If this next 
  2901.    field contains the NULL pointer, this is the end of the chain. 
  2902.  
  2903.  Description 
  2904.  
  2905.  The snmp_dpi_next_packet structure represents a parse tree for a DPI GETNEXT 
  2906.  packet. 
  2907.  
  2908.  At the subagent side, the snmp_dpi_next_packet structure is normally created 
  2909.  as a result of a call to pDPIpacket().  This is the case if the DPI packet is 
  2910.  of type SNMP_DPI_GETNEXT.  The snmp_dpi_hdr structure then contains a pointer 
  2911.  to a chain of one or more snmp_dpi_next_packet structures. 
  2912.  
  2913.  The DPI subagent programmer uses this structure to find out which variables 
  2914.  instances are to be returned in a DPI RESPONSE. 
  2915.  
  2916.  Related Information 
  2917.  
  2918.       The pDPIpacket() Function 
  2919.       The snmp_dpi_hdr Structure 
  2920.  
  2921.  
  2922. ΓòÉΓòÉΓòÉ 6.6. The snmp_dpi_resp_packet Structure ΓòÉΓòÉΓòÉ
  2923.  
  2924. Structure Definition 
  2925.  
  2926. struct dpi_resp_packet {
  2927.   char                   error_code; /* like: SNMP_ERROR_xxx  */
  2928.   unsigned long int      error_index;/* 1st varBind in error  */
  2929.   #define resp_priority  error_index /* if respons to register*/
  2930.   struct dpi_set_packet *varBind_p;  /* ptr to varBind, chain */
  2931.                                      /* of dpi_set_packets    */
  2932. };
  2933. typedef struct dpi_resp_packet       snmp_dpi_resp_packet;
  2934. #define snmp_dpi_resp_packet_NULL_p  ((snmp_dpi_resp_packet *)0)
  2935.  
  2936. Structure Members 
  2937.  
  2938.  error_code 
  2939.    The return code or the error code. 
  2940.  
  2941.    See DPI RESPONSE Error Codes for a list of valid codes. 
  2942.  
  2943.  error_index 
  2944.    Specifies the first varBind is in error.  Counting starts at 1 for the first 
  2945.    varBind.  This field should be zero (SNMP_ERROR_noError) if there is no 
  2946.    error. 
  2947.  
  2948.  resp_priority 
  2949.    This is a redefinition of the error_index field.  If the response is a 
  2950.    response to a DPI REGISTER request and the error_code is equal to 
  2951.    SNMP_ERROR_DPI_noError or SNMP_ERROR_DPI_higherPriorityRegistered, then this 
  2952.    field contains the priority that was actually assigned.  Otherwise, this 
  2953.    field is set to zero for responses to a DPI REGISTER.. 
  2954.  
  2955.  varBind_p 
  2956.    A pointer to the chain of one or more snmp_dpi_set_structures, representing 
  2957.    varBinds of the response.  This field contains a NULL pointer if there are 
  2958.    no varBinds in the response. 
  2959.  
  2960.  Description 
  2961.  
  2962.  The snmp_dpi_resp_packet structure represents a parse tree for a DPI RESPONSE 
  2963.  packet. 
  2964.  
  2965.  The snmp_dpi_resp_packet structure is normally created as a result of a call 
  2966.  to pDPIpacket().  This is the case if the DPI packet is of type 
  2967.  SNMP_DPI_RESPONSE.  The snmp_dpi_hdr structure then contains a pointer to a 
  2968.  snmp_dpi_resp_packet structure. 
  2969.  
  2970.  At the DPI subagent side, a DPI RESPONSE should only be expected at 
  2971.  initialization and termination time when the subagent has issued a DPI OPEN, 
  2972.  DPI REGISTER or DPI UNREGISTER request. 
  2973.  
  2974.  The DPI programmer is advised to use the mkDPIresponse() function to prepare a 
  2975.  DPI RESPONSE packet. 
  2976.  
  2977.  Related Information 
  2978.  
  2979.       The pDPIpacket() Function 
  2980.       The mkDPIresponse() Function 
  2981.       The snmp_dpi_set_packet Structure 
  2982.       The snmp_dpi_hdr Structure 
  2983.  
  2984.  
  2985. ΓòÉΓòÉΓòÉ 6.7. The snmp_dpi_set_packet Structure ΓòÉΓòÉΓòÉ
  2986.  
  2987. Structure Definition 
  2988.  
  2989. struct dpi_set_packet {
  2990.   char             *object_p;    /* ptr to Object ID (string) */
  2991.   char             *group_p;     /* ptr to sub-tree (group)   */
  2992.   char             *instance_p;  /* ptr to rest of OID        */
  2993.   unsigned char     value_type;  /* value type: SNMP_TYPE_xxx */
  2994.   unsigned short    value_len;   /* value length              */
  2995.   char             *value_p;     /* ptr to the value itself   */
  2996.   struct dpi_set_packet *next_p; /* ptr to next in chain      */
  2997. };
  2998. typedef struct dpi_set_packet       snmp_dpi_set_packet;
  2999. #define snmp_dpi_set_packet_NULL_p  ((snmp_dpi_set_packet *)0)
  3000.  
  3001. Structure Members 
  3002.  
  3003.  object_p 
  3004.    A pointer to a NULL terminated character string that represents the full 
  3005.    OBJECT IDENTIFIER of the variable instance that is being accessed.  It 
  3006.    basically is a concatenation of the fields group_p and instance_p.  Using 
  3007.    this field is not recommended because it is only included for DPI Version 1 
  3008.    compatibility and it maybe withdrawn in a later version. 
  3009.  
  3010.  group_p 
  3011.    A pointer to a NULL terminated character string that represents the 
  3012.    registered sub-tree that caused this SET, COMMIT, or UNDO request to be 
  3013.    passed to this DPI subagent.  The sub-tree must have a trailing dot. 
  3014.  
  3015.  instance_p 
  3016.    A pointer to a NULL terminated character string that represents the rest, 
  3017.    which is the piece following the sub-tree part, of the OBJECT IDENTIFIER of 
  3018.    the variable instance being accessed. 
  3019.  
  3020.    Use of the term instance_p here should not be confused with an OBJECT 
  3021.    instance because this string may consist of a piece of the OBJECT IDENTIFIER 
  3022.    plus the INSTANCE IDENTIFIER. 
  3023.  
  3024.  value_type 
  3025.    The type of the value. 
  3026.  
  3027.    See DPI SNMP Value Types for a list of currently defined value types. 
  3028.  
  3029.  value_len 
  3030.    This is an unsigned 16-bit integer that specifies the length in octets of 
  3031.    the value pointed to by the value field.  The length may be zero if the 
  3032.    value if of type SNMP_TYPE_NULL. 
  3033.  
  3034.  value_p 
  3035.    A pointer to the actual value.  This field may contain a NULL pointer if the 
  3036.    value if of type SNMP_TYPE_NULL. 
  3037.  
  3038.    See Value Representation for information on how the data is represented for 
  3039.    the various value types. 
  3040.  
  3041.  next_p 
  3042.    A pointer to a possible next snmp_dpi_set_packet structure.  If this next 
  3043.    field contains the NULL pointer, this is the end of the chain. 
  3044.  
  3045.  Description 
  3046.  
  3047.  The snmp_dpi_set_packet structure represents a parse tree for a DPI SET 
  3048.  request. 
  3049.  
  3050.  The snmp_dpi_set_packet structure may be created as a result of a call to 
  3051.  pDPIpacket().  This is the case if the DPI packet is of type SNMP_DPI_SET, 
  3052.  SNMP_DPI_COMMIT or SNMP_DPI_UNDO.  The snmp_dpi_hdr structure then contains a 
  3053.  pointer to a chain of one or more snmp_dpi_set_packet structures. 
  3054.  
  3055.  This structure can also be created with a mkDPIset() call, which is typically 
  3056.  used when preparing varBinds for a DPI RESPONSE packet. 
  3057.  
  3058.  Related Information 
  3059.  
  3060.       The pDPIpacket() Function 
  3061.       The mkDPIset() Function 
  3062.       DPI SNMP Value Types 
  3063.       Value Representation 
  3064.       The snmp_dpi_hdr Structure 
  3065.  
  3066.  
  3067. ΓòÉΓòÉΓòÉ 6.8. The snmp_dpi_ureg_packet Structure ΓòÉΓòÉΓòÉ
  3068.  
  3069. Structure Definition 
  3070.  
  3071. struct dpi_ureg_packet {
  3072.   char                   reason_code;/* reason for unregister */
  3073.   char                  *group_p;    /* ptr to sub-tree(group)*/
  3074.   struct dpi_reg_packet *next_p;     /* ptr to next in chain  */
  3075. };
  3076. typedef struct dpi_ureg_packet       snmp_dpi_ureg_packet;
  3077. #define snmp_dpi_ureg_packet_NULL_p  ((snmp_dpi_ureg_packet *)0)
  3078.  
  3079. Structure Members 
  3080.  
  3081.  reason_code 
  3082.    The reason for the unregister. 
  3083.  
  3084.    See DPI UNREGISTER Reason Codes for a list of the currently defined reason 
  3085.    codes. 
  3086.  
  3087.  group_p 
  3088.    A pointer to a NULL terminated character string that represents the sub-tree 
  3089.    to be unregistered.  This sub-tree must have a trailing dot. 
  3090.  
  3091.  next_p 
  3092.    A pointer to a possible next snmp_dpi_ureg_packet structure.  If this next 
  3093.    field contains the NULL pointer, this is the end of the chain.  Currently we 
  3094.    do not support multiple unregister requests in one DPI packet, so this field 
  3095.    should always be zero. 
  3096.  
  3097.  Description 
  3098.  
  3099.  The snmp_dpi_ureg_packet structure represents a parse tree for a DPI 
  3100.  UNREGISTER request. 
  3101.  
  3102.  The snmp_dpi_ureg_packet structure is normally created as a result of a call 
  3103.  to pDPIpacket().  This is the case if the DPI packet is of type 
  3104.  SNMP_DPI_UNREGISTER.  The snmp_dpi_hdr structure then contains a pointer to a 
  3105.  snmp_dpi_ureg_packet structure. 
  3106.  
  3107.  The DPI programmer is advised to use the mkDPIunregister() function to create 
  3108.  a DPI UNREGISTER packet. 
  3109.  
  3110.  Related Information 
  3111.  
  3112.       The pDPIpacket() Function 
  3113.       The mkDPIunregister() Function 
  3114.       The snmp_dpi_hdr Structure 
  3115.  
  3116.  
  3117. ΓòÉΓòÉΓòÉ 6.9. The snmp_dpi_u64 Structure ΓòÉΓòÉΓòÉ
  3118.  
  3119. Structure Definition 
  3120.  
  3121. struct snmp_dpi_u64 {           /* for unsigned 64-bit int */
  3122.   unsigned long high;           /* - high order 32 bits    */
  3123.   unsigned long low;            /* - low order  32 bits    */
  3124. };
  3125. typedef struct snmp_dpi_u64     snmp_dpi_u64;
  3126.  
  3127. Note:  This structure is supported only in SNMP Version 2. 
  3128.  
  3129. Structure Members 
  3130.  
  3131.  high 
  3132.    The high order, most significant, 32 bits 
  3133.  
  3134.  low 
  3135.    The low order, least significant, 32 bits 
  3136.  
  3137.  Description 
  3138.  
  3139.  The snmp_dpi_u64 structure represents an unsigned 64-bit integer as need for 
  3140.  values with a type of SNMP_TYPE_Counter64. 
  3141.  
  3142.  The snmp_dpi_u64 structure may be created as a result of a call to 
  3143.  pDPIpacket().  This is the case if the DPI packet is of type SNMP_DPI_SET and 
  3144.  one of the values has a type of SNMP_TYPE_Counter64. The value_p pointer of 
  3145.  the snmp_dpi_set_packet structure will then point to an snmp_dpi_u64 
  3146.  structure. 
  3147.  
  3148.  The DPI programmer must also use an snmp_dpi_u64 structure as the parameter to 
  3149.  a mkDPIset() call if you want to create a value of type SNMP_TYPE_Counter64. 
  3150.  
  3151.  Related Information 
  3152.  
  3153.       The pDPIpacket() Function 
  3154.       The snmp_dpi_set_packet Structure 
  3155.       DPI SNMP Value Types 
  3156.       Value Representation 
  3157.  
  3158.  
  3159. ΓòÉΓòÉΓòÉ 7. Character Set Selection ΓòÉΓòÉΓòÉ
  3160.  
  3161. Based on the character set used on the platform where the agent and subagent 
  3162. are running, you will encounter one of the following three scenarios: 
  3163.  
  3164.      Both run on an ASCII based platform. 
  3165.  
  3166.       In reality a lot of platforms use the ASCII character set.  For those 
  3167.       platforms, just use the native character set.  In that case, the native 
  3168.       character set is ASCII. 
  3169.  
  3170.      Both run on the same non-ASCII based platform. 
  3171.  
  3172.       It is expected that the agent and the subagent normally run on the same 
  3173.       machine or at least on the same platform.  In that case, it is easiest to 
  3174.       use the native character set for data that is represented as strings.  If 
  3175.       such native character set is not the ASCII character set, the agent must 
  3176.       translate from ASCII to the native character set (and vice versa) as 
  3177.       needed. 
  3178.  
  3179.      One runs on ASCII based platform, the other on a non-ASCII based 
  3180.       platform. 
  3181.  
  3182.       If the agent and subagent each run on their own platform and those 
  3183.       platforms use different native character sets; for example, IBM OS/2 uses 
  3184.       ASCII and IBM MVS uses EBCDIC, you must select the ASCII character set, 
  3185.       so that you both know exactly how to represent string-based data that is 
  3186.       being send back and forth.  The entity that is not ASCII based must do 
  3187.       the translation from ASCII to the native character set (and vice versa) 
  3188.       as needed. 
  3189.  
  3190.  When the DPI subagent sends a DPI OPEN packet, it must specify the character 
  3191.  set that it wants to use.  The subagent here needs to know or determine in an 
  3192.  implementation dependent manner if the agent is running on a system with the 
  3193.  same character set as the subagent.  If you connect to the agent at loopback, 
  3194.  localhost, or your own machine, you might assume that you are using the same 
  3195.  character set.  As long as you are just using OS/2 on an Intel based 
  3196.  processor, it does not matter. Always use the native character set, which is 
  3197.  ASCII. 
  3198.  
  3199.  The subagent has two choices: 
  3200.  
  3201.  DPI_NATIVE_CSET       Specifies that you want to use the native character set 
  3202.                        of the platform on which the agent that you connect to 
  3203.                        is running. 
  3204.  
  3205.  DPI_ASCII_CSET        Specifies that you want to use the ASCII character set. 
  3206.                        The agent will translate between ASCII and the native 
  3207.                        character set as required. If the subagent is on a 
  3208.                        non-ASCII based platform, it may have to translate also. 
  3209.  
  3210.  The DPI packets have a number of fields that are represented as strings.  The 
  3211.  fields that must be represented in the selected character set are: 
  3212.  
  3213.      The null terminated string pointed to by the description_p, enterprise_p, 
  3214.       group_p, instance_p, and oid_p parameters in the various mkDPIxxxx(...) 
  3215.       functions. 
  3216.  
  3217.      The string pointed to by the value_p parameter in the mkDPIset(...) 
  3218.       function, that is if the value_type parameter specifies that the value is 
  3219.       an SNMP_TYPE_DisplayString or an SNMP_TYPE_OBJECT_IDENTIFIER. 
  3220.  
  3221.      The null terminated string pointed to by the description_p, enterprise_p, 
  3222.       group_p, instance_p, and oid_p pointers in the various 
  3223.       snmp_dpi_xxxx_packet structures. 
  3224.  
  3225.      The string pointed to by the value_p pointer in the snmp_dpi_set_packet 
  3226.       structure, that is if the value_type field specifies that the value is an 
  3227.       SNMP_TYPE_DisplayString or an SNMP_TYPE_OBJECT_IDENTIFIER. 
  3228.  
  3229.  Related Information 
  3230.  
  3231.       The mkDPIopen() Function 
  3232.  
  3233.  
  3234. ΓòÉΓòÉΓòÉ 8. Constants, Values, Return Codes, and Include File ΓòÉΓòÉΓòÉ
  3235.  
  3236. This section describes all the constants and names for values as they are 
  3237. defined in the snmp_dpi.h include file. 
  3238.  
  3239. Topics 
  3240.  
  3241.       DPI CLOSE Reason Codes 
  3242.       DPI Packet Types 
  3243.       DPI RESPONSE Error Codes 
  3244.       DPI UNREGISTER Reason Codes 
  3245.       DPI SNMP Value Types 
  3246.       Value Representation 
  3247.       Value Ranges and Limits 
  3248.       Return Codes from DPI Transport-Related Functions 
  3249.  
  3250.  
  3251. ΓòÉΓòÉΓòÉ 8.1. DPI CLOSE Reason Codes ΓòÉΓòÉΓòÉ
  3252.  
  3253. The currently defined DPI CLOSE reason codes as defined in the snmp_dpi.h 
  3254. include file are: 
  3255.  
  3256.   #define SNMP_CLOSE_otherReason                 1
  3257.   #define SNMP_CLOSE_goingDown                   2
  3258.   #define SNMP_CLOSE_unsupportedVersion          3
  3259.   #define SNMP_CLOSE_protocolError               4
  3260.   #define SNMP_CLOSE_authenticationFailure       5
  3261.   #define SNMP_CLOSE_byManager                   6
  3262.   #define SNMP_CLOSE_timeout                     7
  3263.   #define SNMP_CLOSE_openError                   8
  3264.  
  3265. These codes are used in the reason_code parameter for the mkDPIclose() function 
  3266. and in the reason_code field in the snmp_dpi_close_packet structure. 
  3267.  
  3268. Related Information 
  3269.  
  3270.       The snmp_dpi_close_packet Structure 
  3271.       The mkDPIclose() Function 
  3272.  
  3273.  
  3274. ΓòÉΓòÉΓòÉ 8.2. DPI Packet Types ΓòÉΓòÉΓòÉ
  3275.  
  3276. The currently defined DPI packet types as defined in the snmp_dpi.h include 
  3277. file are: 
  3278.  
  3279.   #define SNMP_DPI_GET             1
  3280.   #define SNMP_DPI_GET_NEXT        2  /* old DPI 1.x style */
  3281.   #define SNMP_DPI_GETNEXT         2
  3282.   #define SNMP_DPI_SET             3
  3283.   #define SNMP_DPI_TRAP            4
  3284.   #define SNMP_DPI_RESPONSE        5
  3285.   #define SNMP_DPI_REGISTER        6
  3286.   #define SNMP_DPI_UNREGISTER      7
  3287.   #define SNMP_DPI_OPEN            8
  3288.   #define SNMP_DPI_CLOSE           9
  3289.   #define SNMP_DPI_COMMIT         10
  3290.   #define SNMP_DPI_UNDO           11
  3291.   #define SNMP_DPI_GETBULK        12
  3292.   #define SNMP_DPI_TRAPV2         13  /* reserved, not ....    */
  3293.   #define SNMP_DPI_INFORM         14  /* reserved, implemented */
  3294.   #define SNMP_DPI_ARE_YOU_THERE  15
  3295.  
  3296. These packet types are used in the type parameter for the packet_type field in 
  3297. the snmp_dpi_hdr structure. 
  3298.  
  3299. Related Information 
  3300.  
  3301.       The snmp_dpi_hdr Structure 
  3302.  
  3303.  
  3304. ΓòÉΓòÉΓòÉ 8.3. DPI RESPONSE Error Codes ΓòÉΓòÉΓòÉ
  3305.  
  3306. In case of an error on an SNMP request like GET, GETNEXT, GETBULK, SET, COMMIT, 
  3307. or UNDO, the RESPONSE can have one of these currently defined error codes. 
  3308. They are defined in the snmp_dpi.h include file: 
  3309.  
  3310.   #define SNMP_ERROR_noError               0
  3311.   #define SNMP_ERROR_tooBig                1
  3312.   #define SNMP_ERROR_noSuchName            2
  3313.   #define SNMP_ERROR_badValue              3
  3314.   #define SNMP_ERROR_readOnly              4
  3315.   #define SNMP_ERROR_genErr                5
  3316.   #define SNMP_ERROR_noAccess              6
  3317.   #define SNMP_ERROR_wrongType             7
  3318.   #define SNMP_ERROR_wrongLength           8
  3319.   #define SNMP_ERROR_wrongEncoding         9
  3320.   #define SNMP_ERROR_wrongValue           10
  3321.   #define SNMP_ERROR_noCreation           11
  3322.   #define SNMP_ERROR_inconsistentValue    12
  3323.   #define SNMP_ERROR_resourceUnavailable  13
  3324.   #define SNMP_ERROR_commitFailed         14
  3325.   #define SNMP_ERROR_undoFailed           15
  3326.   #define SNMP_ERROR_authorizationError   16
  3327.   #define SNMP_ERROR_notWritable          17
  3328.   #define SNMP_ERROR_inconsistentName     18
  3329.  
  3330. In case of an error on a DPI only request (OPEN, REGISTER, UNREGISTER, 
  3331. ARE_YOU_THERE), the RESPONSE can have one of these currently defined error 
  3332. codes.  They are defined in the snmp_dpi.h include file: 
  3333.  
  3334.   #define SNMP_ERROR_DPI_noError                        0
  3335.   #define SNMP_ERROR_DPI_otherError                   101
  3336.   #define SNMP_ERROR_DPI_notFound                     102
  3337.   #define SNMP_ERROR_DPI_alreadyRegistered            103
  3338.   #define SNMP_ERROR_DPI_higherPriorityRegistered     104
  3339.   #define SNMP_ERROR_DPI_mustOpenFirst                105
  3340.   #define SNMP_ERROR_DPI_notAuthorized                106
  3341.   #define SNMP_ERROR_DPI_viewSelectionNotSupported    107
  3342.   #define SNMP_ERROR_DPI_getBulkSelectionNotSupported 108
  3343.   #define SNMP_ERROR_DPI_duplicateSubAgentIdentifier  109
  3344.   #define SNMP_ERROR_DPI_invalidDisplayString         110
  3345.   #define SNMP_ERROR_DPI_characterSetSelectionNotSupported  111
  3346.  
  3347. These codes are used in the error_code parameter for the mkDPIresponse() 
  3348. function and in the error_code field in the snmp_dpi_resp_packet structure. 
  3349.  
  3350. Related Information 
  3351.  
  3352.       The snmp_dpi_resp_packet Structure 
  3353.       The mkDPIresponse() Function 
  3354.  
  3355.  
  3356. ΓòÉΓòÉΓòÉ 8.4. DPI UNREGISTER Reason Codes ΓòÉΓòÉΓòÉ
  3357.  
  3358. These are the currently defined DPI UNREGISTER reason codes.  They are define 
  3359. in the snmp_dpi.h include file: 
  3360.  
  3361.   #define SNMP_UNREGISTER_otherReason               1
  3362.   #define SNMP_UNREGISTER_goingDown                 2
  3363.   #define SNMP_UNREGISTER_justUnregister            3
  3364.   #define SNMP_UNREGISTER_newRegistration           4
  3365.   #define SNMP_UNREGISTER_higherPriorityRegistered  5
  3366.   #define SNMP_UNREGISTER_byManager                 6
  3367.   #define SNMP_UNREGISTER_timeout                   7
  3368.  
  3369. These codes are used in the reason_code parameter for the mkDPIunregister() 
  3370. function and in the reason_code field in the snmp_dpi_ureg_packet structure. 
  3371.  
  3372. Related Information 
  3373.  
  3374.       The snmp_dpi_ureg_packet Structure 
  3375.       The mkDPIunregister() Function 
  3376.  
  3377.  
  3378. ΓòÉΓòÉΓòÉ 8.5. DPI SNMP Value Types ΓòÉΓòÉΓòÉ
  3379.  
  3380. These are the currently defined value types as defined in the snmp_dpi.h 
  3381. include file: 
  3382.  
  3383. #define SNMP_TYPE_MASK           0x7f  /* mask to isolate type*/
  3384. #define SNMP_TYPE_Integer32    (128|1) /* 32-bit INTEGER      */
  3385. #define SNMP_TYPE_OCTET_STRING      2  /* OCTET STRING        */
  3386. #define SNMP_TYPE_OBJECT_IDENTIFIER 3  /* OBJECT IDENTIFIER   */
  3387. #define SNMP_TYPE_NULL              4  /* NULL, no value      */
  3388. #define SNMP_TYPE_IpAddress         5  /* IMPLICIT OCTETSTRING*/
  3389. #define SNMP_TYPE_Counter32    (128|6) /* 32-bit Counter      */
  3390. #define SNMP_TYPE_Gauge32      (128|7) /* 32-bit Gauge        */
  3391. #define SNMP_TYPE_TimeTicks    (128|8) /* 32-bit TimeTicks in */
  3392.                                        /* hundredths of a sec */
  3393. #define SNMP_TYPE_DisplayString     9  /* DisplayString (TC)  */
  3394. #define SNMP_TYPE_BIT_STRING       10  /* BIT STRING          */
  3395. #define SNMP_TYPE_NsapAddress      11  /* IMPLICIT OCTETSTRING*/
  3396. #define SNMP_TYPE_UInteger32  (128|12) /* 32-bit INTEGER      */
  3397. #define SNMP_TYPE_Counter64        13  /* 64-bit Counter      */
  3398. #define SNMP_TYPE_Opaque           14  /* IMPLICIT OCTETSTRING*/
  3399. #define SNMP_TYPE_noSuchObject     15  /* IMPLICIT NULL       */
  3400. #define SNMP_TYPE_noSuchInstance   16  /* IMPLICIT NULL       */
  3401. #define SNMP_TYPE_endOfMibView     17  /* IMPLICIT NULL       */
  3402.  
  3403. These value types are used in the value_type parameter for the mkDPIset() 
  3404. function and in the value_type field in the snmp_dpi_set_packet structure. 
  3405.  
  3406. Related Information 
  3407.  
  3408.       The snmp_dpi_set_packet Structure 
  3409.       The mkDPIset() Function 
  3410.       Value Representation 
  3411.       Value Ranges and Limits 
  3412.  
  3413.  
  3414. ΓòÉΓòÉΓòÉ 8.6. Value Representation ΓòÉΓòÉΓòÉ
  3415.  
  3416. Values in the snmp_dpi_set_packet structure are represented as follows: 
  3417.  
  3418.      32-bit integers are defined as long int or unsigned long int.  We assume 
  3419.       that a long int is 4 bytes. 
  3420.  
  3421.      64-bit integers are represented as an snmp_dpi_u64. 
  3422.  
  3423.       We only deal with unsigned 64 bit integers in SNMP.  In a structure that 
  3424.       has two fields, the high order piece and the low order piece, each is of 
  3425.       type unsigned long int.  We assume these are 4-bytes. 
  3426.  
  3427.      Object Identifiers are NULL terminated strings in the selected character 
  3428.       set, representing the OID in ASN.1 dotted notation.  The length includes 
  3429.       the terminating NULL. 
  3430.  
  3431.       An ASCII example: 
  3432.  
  3433.             '312e332e362e312e322e312e312e312e3000'h
  3434.  
  3435.       represents "1.3.6.1.2.1.1.1.0" which is sysDescr.0. 
  3436.  
  3437.       An EBCDIC example: 
  3438.  
  3439.             'f14bf34bf64bf14bf24bf14bf14bf14bf000'h
  3440.  
  3441.       represents "1.3.6.1.2.1.1.1.0" which is sysDescr.0. 
  3442.  
  3443.      DisplayStrings are in the selected character set.  The length specifies 
  3444.       the length of the string. 
  3445.  
  3446.       An ASCII example: 
  3447.  
  3448.             '6162630d0a'h
  3449.  
  3450.       represents "abc\r\n", no NULL. 
  3451.  
  3452.       An EBCDIC example: 
  3453.  
  3454.             '8182830d25'h
  3455.  
  3456.       represents "abc\r\n", no NULL. 
  3457.  
  3458.      IpAddress, NsapAddress, and Opaque are implicit OCTET_STRING, so they are 
  3459.       a sequence of octets/bytes.  This means, for instance, that the IP 
  3460.       address is in network byte order. 
  3461.  
  3462.      NULL has a zero length for the value, no value data, so a NULL pointer in 
  3463.       the value_p field. 
  3464.  
  3465.      noSuchObject, noSuchInstance, and endOfMibView are implicit NULL and 
  3466.       represented as such. 
  3467.  
  3468.      BIT_STRING is an OCTET_STRING of the form uubbbb...bb, where the first 
  3469.       octet (uu) is 0x00-0x07 and indicates the number of unused bits in the 
  3470.       last octet (bb).  The bb octets represent the bit string itself, where 
  3471.       bit zero (0) comes first and so on. 
  3472.  
  3473.  Related Information 
  3474.  
  3475.       Value Ranges and Limits 
  3476.  
  3477.  
  3478. ΓòÉΓòÉΓòÉ 8.7. Value Ranges and Limits ΓòÉΓòÉΓòÉ
  3479.  
  3480. The following rules apply to object IDs in ASN.1 notation: 
  3481.  
  3482.      The object ID consists of 1 to 128 subIDs, which are separated by dots. 
  3483.  
  3484.      Each subID is a positive number.  No negative numbers are allowed. 
  3485.  
  3486.      The value of each number cannot exceed 4294967295 (4,294,967,295). This 
  3487.       value is 2 to the power of 32 minus 1. 
  3488.  
  3489.      The valid values of the first subID are: 0, 1, or 2. 
  3490.  
  3491.      If the first subID has a value of 0 or 1, the second subID can only have 
  3492.       a value of 0 through 39. 
  3493.  
  3494.  The following rules apply to DisplayString: 
  3495.  
  3496.      A DisplayString (Textual Convention) is basically an OCTET STRING in SNMP 
  3497.       terms. 
  3498.  
  3499.      The maximum size of a DisplayString is 255 octets/bytes. 
  3500.  
  3501.      The octets of a DisplayString must belong to the ASCII NVT character set. 
  3502.       This character set is not precisely defined, but commonly accepted to 
  3503.       consist of all ASCII characters with a value in the range of 0-127 
  3504.       inclusive. 
  3505.  
  3506.       A further limitation is that the CR (hex 13) must always be followed by 
  3507.       either a LF (hex 0A) or a  NUL (hex 00). 
  3508.  
  3509.  More information on the DPI SNMP value types can be found in the SNMP SMI 
  3510.  (Structure of Management Information) and SNMP TC (Textual Conventions) RFCs. 
  3511.  At the time of this publication, these two RFCs are RFC1442 and RFC1443. 
  3512.  
  3513.  
  3514. ΓòÉΓòÉΓòÉ 8.8. Return Codes from DPI Transport-Related Functions ΓòÉΓòÉΓòÉ
  3515.  
  3516. These are the currently defined values for the return codes from DPI 
  3517. transport-related functions.  They are defined in the snmp_dpi.h include file: 
  3518.  
  3519. #define DPI_RC_OK                0 /* all OK, no error         */
  3520. #define DPI_RC_NOK              -1 /* some other error         */
  3521. #define DPI_RC_NO_PORT          -2 /* can't determine DPIport  */
  3522. #define DPI_RC_NO_CONNECTION    -3 /* no connection to DPIagent*/
  3523. #define DPI_RC_EOF              -4 /* EOF receivd on connection*/
  3524. #define DPI_RC_IO_ERROR         -5 /* Some I/O error on connect*/
  3525. #define DPI_RC_INVALID_HANDLE   -6 /* unknown/invalid handle   */
  3526. #define DPI_RC_TIMEOUT          -7 /* timeout occurred         */
  3527. #define DPI_RC_PACKET_TOO_LARGE -8 /* packed too large, dropped*/
  3528.  
  3529. These values are used as return codes for the transport-related DPI functions. 
  3530.  
  3531. Related Information 
  3532.  
  3533.       The DPIconnect_to_agent_TCP() Function 
  3534.       The DPIconnect_to_agent_SHM() Function 
  3535.       The DPIawait_packet_from_agent() Function 
  3536.       The DPIsend_packet_to_agent() Function 
  3537.  
  3538.  
  3539. ΓòÉΓòÉΓòÉ 8.9. The snmp_dpi.h Include File ΓòÉΓòÉΓòÉ
  3540.  
  3541. Syntax 
  3542.  
  3543. #include <snmp_dpi.h>
  3544.  
  3545. Parameters 
  3546.  
  3547.    None. 
  3548.  
  3549.  Description 
  3550.  
  3551.  The snmp_dpi.h include file defines the SNMP DPI API to the DPI subagent 
  3552.  programmer.  It has all the function proto-type statements, and it also has 
  3553.  the definitions for the snmp_dpi structures. 
  3554.  
  3555.  The same include file is used at the agent side, so you will see some 
  3556.  definitions which are unique to the agent side.  Also there may be other 
  3557.  functions or prototypes of functions not implemented on OS/2. Therefore, you 
  3558.  should only use the API as far as it is documented in this information. 
  3559.  
  3560.  Related Information 
  3561.  
  3562.  Macros, functions, structures, constants and values defined in the snmp_dpi.h 
  3563.  include file are: 
  3564.  
  3565.       The DPIawait_packet_from_agent() Function 
  3566.       The DPIconnect_to_agent_TCP() Function 
  3567.       The DPIdebug() Function 
  3568.       The DPIdisconnect_from_agent() Function 
  3569.       The DPI_PACKET_LEN() Macro 
  3570.       The DPIsend_packet_to_agent() Function 
  3571.       The fDPIparse() Function 
  3572.       The fDPIset() Function 
  3573.       The mkDPIAreYouThere() Function 
  3574.       The mkDPIclose() Function 
  3575.       The mkDPIopen() Function 
  3576.       The mkDPIregister() Function 
  3577.       The mkDPIresponse() Function 
  3578.       The mkDPIset() Function 
  3579.       The mkDPItrap() Function 
  3580.       The mkDPIunregister() Function 
  3581.       The pDPIpacket() Function 
  3582.       The snmp_dpi_close_packet Structure 
  3583.       The snmp_dpi_get_packet Structure 
  3584.       The snmp_dpi_next_packet Structure 
  3585.       The snmp_dpi_bulk_packet Structure 
  3586.       The snmp_dpi_hdr Structure 
  3587.       The lookup_host() Function 
  3588.       The query_DPI_port() Function 
  3589.       The snmp_dpi_resp_packet Structure 
  3590.       The snmp_dpi_set_packet Structure 
  3591.       The snmp_dpi_ureg_packet Structure 
  3592.       DPI CLOSE Reason Codes 
  3593.       DPI Packet Types 
  3594.       DPI RESPONSE Error Codes 
  3595.       DPI UNREGISTER Reason Codes 
  3596.       DPI SNMP Value Types 
  3597.       Character Set Selection 
  3598.  
  3599.  
  3600. ΓòÉΓòÉΓòÉ 9. SNMP DPI API Version 1.1 Considerations ΓòÉΓòÉΓòÉ
  3601.  
  3602. The information presented in this section must be taken as guidelines and not 
  3603. exact procedures.  Your specific implementation will vary from the guidelines 
  3604. presented. 
  3605.  
  3606. You can keep your existing DPI 1.1 subagent and communicate with a DPI capable 
  3607. agent that supports DPI 1.1 in addition to DPI 2.0.  For example, the 
  3608. SystemView Agent provides support for multiple versions of DPI, namely Version 
  3609. 1.1 and Version 2.0. 
  3610.  
  3611. Note:  Although DPI Version 1.1 is supported, it is recommended that you 
  3612. migrate to Version 2.0. 
  3613.  
  3614. Normally you would compile your DPI 1.1 subagent with the DPI 1.1 
  3615. <dpi\snmp_dpi.h> include file and link-edit it with the DPI 1.1 level 
  3616. DPI32DLL.LIB.  At run time, you then need access to the DPI32DLL.DLL.  You can 
  3617. continue to do this until you are ready to migrate to DPI Version 2.0. 
  3618.  
  3619. In the snmp_dpi.h include file for DPI 2.0, you may find references to DPI 1.1 
  3620. compatibility mode under control of compiler flags, such as: 
  3621.  
  3622.    /DSNMP_DPI_VERSION=1 /DSNMP_DPI_RELEASE=0
  3623.    /DSNMP_DPI_VERSION=1 /DSNMP_DPI_RELEASE=1
  3624.  
  3625. However, this compatibility mode is not provided with the SystemView Agent.  If 
  3626. you want to convert to DPI 2.0, which prepares you also for SNMP Version 2, you 
  3627. must make changes to your code. 
  3628.  
  3629. Name Changes 
  3630.  
  3631. A number of field names in the snmp_dpi_xxxx_packet structures have changed so 
  3632. that the names are now more consistent throughout the DPI code. 
  3633.  
  3634. The new names indicate if the value is a pointer (_p) or a union (_u).  The 
  3635. names that have changed and that affect the subagent code are listed in the 
  3636. table below. 
  3637.  
  3638. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  3639. Γöé OLD NAME    Γöé NEW NAME    Γöé DATA STRUCTURE(XXXX)   Γöé
  3640. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3641. Γöé group_id    Γöé group_p     Γöé getnext         Γöé
  3642. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3643. Γöé object_id    Γöé object_p    Γöé get, getnext, set    Γöé
  3644. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3645. Γöé value      Γöé value_p     Γöé set           Γöé
  3646. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3647. Γöé type      Γöé value_type   Γöé set           Γöé
  3648. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3649. Γöé next      Γöé next_p     Γöé set           Γöé
  3650. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3651. Γöé enterprise   Γöé enterprise_p  Γöé trap           Γöé
  3652. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3653. Γöé packet_body   Γöé data_u     Γöé dpi_hdr         Γöé
  3654. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3655. Γöé dpi_get     Γöé get_p      Γöé hdr (packet_body)    Γöé
  3656. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3657. Γöé dpi_getnext   Γöé next_p     Γöé hdr (packet_body)    Γöé
  3658. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3659. Γöé dpi_set     Γöé set_p      Γöé hdr (packet_body)    Γöé
  3660. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3661. Γöé dpi_trap    Γöé trap_p     Γöé hdr (packet_body)    Γöé
  3662. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  3663. Γöé         Γöé         Γöé             Γöé
  3664. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  3665.  
  3666. There is no clean approach to make this change transparent.  You probably will 
  3667. have to change the names in your code.  You may want to try a simple set of 
  3668. defines like: 
  3669.  
  3670. #define packet_body      data_u
  3671. #define dpi_get          get_p
  3672. #define dpi_set          set_p
  3673. #define dpi_next         next_p
  3674. #define dpi_response     resp_p
  3675. #define dpi_trap         trap_p
  3676. #define group_id         group_p
  3677. #define object_id        object_p
  3678. #define value            value_p
  3679. #define type             value_type
  3680. #define next             next_p
  3681. #define enterprise       enterprise_p
  3682.  
  3683. However, the names may conflict with other definitions that you have, in which 
  3684. case you must change your code. 
  3685.  
  3686. Related Information 
  3687.  
  3688.       Migrating Your SNMP DPI Subagent to Version 2.0 
  3689.  
  3690.  
  3691. ΓòÉΓòÉΓòÉ 10. Migrating Your SNMP DPI Subagent to Version 2.0 ΓòÉΓòÉΓòÉ
  3692.  
  3693. The information presented in this section must be taken as guidelines and not 
  3694. exact procedures.  Your specific implementation will vary from the guidelines 
  3695. presented. 
  3696.  
  3697. When you want to change your DPI 1.x based subagent code to the DPI Version 2.0 
  3698. level use these guidelines for the required actions and the recommended 
  3699. actions. 
  3700.  
  3701. Required Actions 
  3702.  
  3703.      Add a mkDPIopen() call and send the created packet to the agent. This 
  3704.       opens your "DPI connection" with the agent.  Wait for the response and 
  3705.       ensure that the open is accepted.  You need to pass a subagent ID (Object 
  3706.       Identifier) which must be a unique ASN.1 OID. 
  3707.  
  3708.       See The mkDPIopen() Function for more information. 
  3709.  
  3710.      Change your mkDPIregister() calls and pass the parameters according to 
  3711.       the new function prototype.  You must also expect a RESPONSE to the 
  3712.       REGISTER request. 
  3713.  
  3714.       See The mkDPIregister() Function for more information. 
  3715.  
  3716.      Change mkDPIset() and/or mkDPIlist() calls to the new mkDPIset() call. 
  3717.       Basically all mkDPIset() calls are now of the DPI 1.1 mkDPIlist() form. 
  3718.  
  3719.       See The mkDPIset() Function for more information. 
  3720.  
  3721.      Change mkDPItrap() and mkDPItrape() calls to the new mkDPItrap() call. 
  3722.       Basically all mkDPItrap() calls are now of the DPI 1.1 mkDPItrape() form. 
  3723.  
  3724.       See The mkDPItrap() Function for more information. 
  3725.  
  3726.      Add code to recognize DPI RESPONSE packets, which should be expected as a 
  3727.       result of OPEN, REGISTER, UNREGISTER requests. 
  3728.  
  3729.      Add code to expect and handle the DPI UNREGISTER packet from the agent. 
  3730.       It may send such packets if an error occurs or if a higher priority 
  3731.       subagent registers the same sub-tree as you have registered. 
  3732.  
  3733.      Add code to unregister your sub-tree(s) and close the "DPI connection" 
  3734.       when you want to terminate the subagent. 
  3735.  
  3736.       See The mkDPIunregister() Function and The mkDPIclose() Function for more 
  3737.       information. 
  3738.  
  3739.      Change your code to use the new SNMP Version 2 error codes as defined in 
  3740.       the snmp_dpi.h include file. 
  3741.  
  3742.      Change your code that handles a GET request.  It should return a varBind 
  3743.       with SNMP_TYPE_noSuchObject value or SNMP_TYPE_noSuchInstance value 
  3744.       instead of an error SNMP_ERROR_noSuchName if the object or the instance 
  3745.       do not exist.  This is not considered an error any more. Therefore, you 
  3746.       should return an SNMP_ERROR_noError with an error index of zero. 
  3747.  
  3748.      Change your code that handles a GETNEXT request.  It should return a 
  3749.       varBind with SNMP_TYPE_endOfMibView value instead of an error 
  3750.       SNMP_ERROR_noSuchName if you reach the end of your MIB or sub-tree. This 
  3751.       is not considered an error any more.  Therefore, you should return an 
  3752.       SNMP_ERROR_noError with an error index of zero. 
  3753.  
  3754.      Change your code that handles SET requests to follow the two phase 
  3755.       SET/COMMIT scheme as described in SET Processing. 
  3756.  
  3757.       See the sample handling of SET/COMMIT/UNDO in Processing a 
  3758.       SET/COMMIT/UNDO Request. 
  3759.  
  3760.  Recommended Actions 
  3761.  
  3762.      Do not reference the object ID pointer (object_p) in the 
  3763.       snmp_dpi_xxxx_packet structures anymore.  Instead start using the group_p 
  3764.       and instance_p pointers.  The object_p pointer may be removed in a future 
  3765.       version of the DPI API. 
  3766.  
  3767.      Check Transport-Related DPI API Functions to see if you want to use those 
  3768.       functions instead of using your own code for those functions. 
  3769.  
  3770.      Consider using more than 1 varBind per DPI packet.  You can specify this 
  3771.       on the REGISTER request.  You must then be prepared to handle multiple 
  3772.       varBinds per DPI packet.  The varBinds are chained via the various 
  3773.       snmp_dpi_xxxx_packet structures. 
  3774.  
  3775.       See The mkDPIregister() Function for more information. 
  3776.  
  3777.      Consider specifying a time out when you issue a DPI OPEN or DPI REGISTER. 
  3778.  
  3779.       See The mkDPIopen() Function and The mkDPIregister() Function for more 
  3780.       information. 
  3781.  
  3782.  
  3783. ΓòÉΓòÉΓòÉ 11. A DPI Subagent Example ΓòÉΓòÉΓòÉ
  3784.  
  3785. This is an example of a DPI subagent.  The code is in the "dpi_samp.c" file. 
  3786.  
  3787. Note:  The example code presented here was copied from the sample file at the 
  3788. time of the publication.  For the most up-to-date example code, please see the 
  3789. SVA\DPI directory.  There may be differences in the code presented and the code 
  3790. that is shipped with the product.  Always use the code provided in the SVA\DPI 
  3791. directory as the authoritative sample code. 
  3792.  
  3793. Topics 
  3794.  
  3795.       Overview of Subagent Processing 
  3796.       Connecting to the Agent 
  3797.       Registering a Sub-Tree with the Agent 
  3798.       Processing Requests from the Agent 
  3799.       Processing a GET Request 
  3800.       Processing a GETNEXT Request 
  3801.       Processing a SET/COMMIT/UNDO Request 
  3802.       Processing an UNREGISTER Request 
  3803.       Processing an CLOSE Request 
  3804.       Generating a TRAP 
  3805.  
  3806.  Related Information 
  3807.  
  3808.       Subagent Programming Concepts 
  3809.  
  3810.  
  3811. ΓòÉΓòÉΓòÉ 11.1. Overview of Subagent Processing ΓòÉΓòÉΓòÉ
  3812.  
  3813. This overview assumes that the subagent communicates with the agent over a TCP 
  3814. connection.  Other connection implementations are possible and, in that case, 
  3815. the processing approach may be a bit different. 
  3816.  
  3817. We also take a simplistic approach in the sense that we will request the agent 
  3818. to send us at most one varBind per DPI packet, so we do not need to loop 
  3819. through a list of varBinds.  Potentially, you may gain performance improvements 
  3820. if you allow for multiple varBinds per DPI packet on GET, GETNEXT, SET 
  3821. requests, but to do so, your code will have to loop through the varBind list 
  3822. and so it becomes somewhat more complicated.  We assume that the DPI subagent 
  3823. programmer can handle that once you understand the basics of the DPI API. 
  3824.  
  3825. Here is the dpiSimple MIB definition as it is implemented by the sample code, 
  3826. which follows: 
  3827.  
  3828. DPISimple-MIB DEFINITIONS ::= BEGIN
  3829.  
  3830.    IMPORTS
  3831.         MODULE-IDENTITY, OBJECT-TYPE, snmpModules, enterprises
  3832.                    FROM SNMPv2-SMI
  3833.         DisplayString
  3834.                    FROM SNMPv2-TC
  3835.  
  3836.    ibm      OBJECT IDENTIFIER ::= { enterprises 2 }
  3837.    ibmDPI   OBJECT IDENTIFIER ::= { ibm 2 }
  3838.    dpi20MIB OBJECT IDENTIFIER ::= { ibmDPI 1 }
  3839.  
  3840.  
  3841.    dpiSimpleMIB OBJECT IDENTIFIER ::= { dpi20MIB 5 }
  3842.  
  3843.    dpiSimpleInteger         OBJECT-TYPE
  3844.         SYNTAX  INTEGER
  3845.         ACCESS  read-only
  3846.         STATUS  mandatory
  3847.         DESCRIPTION
  3848.             "A sample integer32 value"
  3849.         ::= { dpiSimpleMIB 1 }
  3850.  
  3851.    dpiSimpleString          OBJECT-TYPE
  3852.         SYNTAX  DisplayString
  3853.         ACCESS  read-write
  3854.         STATUS  mandatory
  3855.         DESCRIPTION
  3856.             "A sample Display String"
  3857.         ::= { dpiSimpleMIB 2 }
  3858.  
  3859.    dpiSimpleCounter32       OBJECT-TYPE
  3860.         SYNTAX  Counter     -- Counter32 is SNMPv2
  3861.         ACCESS  read-only
  3862.         STATUS  mandatory
  3863.         DESCRIPTION
  3864.             "A sample 32-bit counter"
  3865.         ::= { dpiSimpleMIB 3 }
  3866.  
  3867.    dpiSimpleCounter64       OBJECT-TYPE
  3868.         SYNTAX  Counter64   -- Counter64 is SNMPv2,
  3869.                             -- Not supported by SNMPv1 agents
  3870.         ACCESS  read-only
  3871.         STATUS  mandatory
  3872.         DESCRIPTION
  3873.             "A sample 64-bit counter"
  3874.         ::= { dpiSimpleMIB 4 }
  3875. END
  3876.  
  3877. To make the code more readable, we have defined the following names in our 
  3878. dpi_samp.c source file. 
  3879.  
  3880. #define DPI_SIMPLE_SUBAGENT   "1.3.6.1.4.1.2.2.1.5"
  3881. #define DPI_SIMPLE_MIB        "1.3.6.1.4.1.2.2.1.5."
  3882. #define DPI_SIMPLE_INTEGER    "1.0"  /* dpiSimpleInteger.0   */
  3883. #define DPI_SIMPLE_STRING     "2.0"  /* dpiSimpleString.0    */
  3884. #define DPI_SIMPLE_COUNTER32  "3.0"  /* dpiSimpleCounter32.0 */
  3885. #define DPI_SIMPLE_COUNTER64  "4.0"  /* dpiSimpleCounter64.0 */
  3886.  
  3887. In addition, we have defined the following variables as global variable in our 
  3888. dpi_samp.c source file. 
  3889.  
  3890. static int handle;                        /* handle has global scope */
  3891. static long int      value1      = 5;
  3892. #define              value2_p      cur_val_p   /* writable object    */
  3893. #define              value2_len    cur_val_len /* writable object    */
  3894. static char         *cur_val_p   = (char *)0;
  3895. static char         *new_val_p   = (char *)0;
  3896. static char         *old_val_p   = (char *)0;
  3897. static unsigned long cur_val_len = 0;
  3898. static unsigned long new_val_len = 0;
  3899. static unsigned long old_val_len = 0;
  3900. static unsigned long value3      = 1;
  3901. static snmp_dpi_u64  value4      = {0x80000000,1L};
  3902.  
  3903.  
  3904. ΓòÉΓòÉΓòÉ 11.2. Connecting to the Agent ΓòÉΓòÉΓòÉ
  3905.  
  3906. Before a subagent can receive or send any DPI packets from/to the SNMP DPI 
  3907. capable agent, it must "connect" to the agent and identify itself to the agent. 
  3908.  
  3909. The following example code returns a response.  We assume that there are no 
  3910. errors in the request, but proper code should do the checking for that.  We do 
  3911. proper checking for lexicographic next object, but we do no checking for 
  3912. ULONG_MAX, or making sure that the instance ID is indeed valid (digits and 
  3913. dots).  If we get to the end of our dpiSimpleMIB, we must return an 
  3914. endOfMibView as defined by the SNMP Version 2 rules. 
  3915.  
  3916.      A host name or IP address in dot notation that specifies where the agent 
  3917.       is running.  Often the name "loopback" or "localhost" can be used if the 
  3918.       subagent runs on the same system as the agent. 
  3919.  
  3920.      A community name which is used to obtain the DPI TCP port from the agent. 
  3921.       Internally that is done by sending a regular SNMP GET request to the 
  3922.       agent.  In an open environment, we probably can use the well know 
  3923.       community name "public". 
  3924.  
  3925.  The function returns a negative error code if an error occurs.  If the 
  3926.  connection setup is successful, it returns a handle which represents the 
  3927.  connection and which we must use on subsequent calls to send or await DPI 
  3928.  packets. 
  3929.  
  3930.  The second step is to identify the subagent to the agent.  This is done by 
  3931.  making a DPI-OPEN packet, sending it to the agent, and then awaiting the 
  3932.  response from the agent.  The agent may accept or deny the OPEN request. 
  3933.  Making a DPI-OPEN packet is done by calling mkDPIopen() which expects the 
  3934.  following parameters: 
  3935.  
  3936.      A unique subagent identification (an Object Identifier). 
  3937.  
  3938.      A description which can be the NULL string (""). 
  3939.  
  3940.      Overall subagent timeout in seconds.  The agent uses this value as a 
  3941.       timeout value for a response when it sends a request to the subagent. 
  3942.       The agent may have a maximum value for this timeout that will be used if 
  3943.       you exceed it. 
  3944.  
  3945.      The maximum number of varBinds per DPI packet that the subagent is 
  3946.       willing or is able to handle. 
  3947.  
  3948.      The character set we want to use.  In most cases you want to use the 
  3949.       native character set. 
  3950.  
  3951.      Length of a password.  A zero means no password. 
  3952.  
  3953.      Pointer to the password or NULL if no password.  It depends on the agent 
  3954.       if subagents must specify a password to open up a connection. 
  3955.  
  3956.  The function returns a pointer to a static buffer holding the DPI packet if 
  3957.  successful.  If it fails, it returns a NULL pointer. 
  3958.  
  3959.  Once the DPI-OPEN packet has been created, you must send it to the agent.  You 
  3960.  can use the DPIsend_packet_to_agent() function which expects the following 
  3961.  parameters: 
  3962.  
  3963.      The handle of a connection from DPIconnect_to_agent_TCP. 
  3964.  
  3965.      A pointer to the DPI packet from mkDPIopen. 
  3966.  
  3967.      The length of the packet.  The snmp_dpi.h include file provides a macro 
  3968.       DPI_PACKET_LEN that calculates the packet length of a DPI packet. 
  3969.  
  3970.  This function returns DPI_RC_OK (value zero) if successful. Otherwise, an 
  3971.  appropriate DPI_RC_xxxx error code as defined in snmp_dpi.h is returned. 
  3972.  
  3973.  Now we must wait for a response to the DPI-OPEN.  To await such a response, 
  3974.  you call the DPIawait_packet_from_agent() function which expects the following 
  3975.  parameters: 
  3976.  
  3977.      The handle of a connection from DPIconnect_to_agent_TCP. 
  3978.  
  3979.      A timeout in seconds, which is the maximum time to wait for response. 
  3980.  
  3981.      A pointer to a pointer, which will receive a pointer to a static buffer 
  3982.       containing the awaited DPI packet.  If the system fails to receive a 
  3983.       packet, a NULL pointer is stored. 
  3984.  
  3985.      A pointer to a long integer (32-bit), which will receive the length of 
  3986.       the awaited packet.  If it fails, it will be set to zero. 
  3987.  
  3988.  This function returns DPI_RC_OK (value zero) if successful. Otherwise, an 
  3989.  appropriate DPI_RC_xxxx error code as defined in snmp_dpi.h is returned. 
  3990.  
  3991.  The last step is to ensure that we received a DPI-RESPONSE back from the 
  3992.  agent.  If we did, then we must ensure that the agent accepted us as a valid 
  3993.  subagent.  This will be shown by the error_code field in the DPI response 
  3994.  packet. 
  3995.  
  3996.  The following example code establishes a connection and "opens" it by 
  3997.  identifying yourself to the agent. 
  3998.  
  3999.   #include <snmp_dpi.h>              /* DPI 2.0 API definitions */
  4000.   static int handle;                 /* handle has global scope */
  4001.  
  4002.   static void do_connect_and_open(char *hostname_p, char *community_p) {
  4003.          unsigned char *packet_p;
  4004.          int            rc;
  4005.          unsigned long  length;
  4006.          snmp_dpi_hdr  *hdr_p;
  4007.          if (shared_mem) {           /* if shared memory wanted */
  4008.             handle =                 /* then (SHM) connect to   */
  4009.                DPIconnect_to_agent_SHM(1);
  4010.                                      /* always use 1 as queueID */
  4011.          } else {
  4012.             handle =
  4013.                   DPIconnect_to_agent_TCP(
  4014.                                      /* (TCP) connect to agent  */
  4015.                      hostname_p,     /* on this host            */
  4016.                      community_p);   /* snmp community name     */
  4017.          } /* endif */
  4018.          if (handle < 0) exit(1);    /* If it failed, exit      */
  4019.          packet_p = mkDPIopen(       /* Make DPI-OPEN packet    */
  4020.                       DPI_SIMPLE_SUBAGENT,
  4021.                                      /* Our identification      */
  4022.                      "Simple DPI subAgent",
  4023.                                      /* description             */
  4024.                       10L,           /* Our overall timeout     */
  4025.                       1L,            /* max varBinds/packet     */
  4026.                       DPI_NATIVE_CSET,
  4027.                                      /* native character set    */
  4028.                       0L,            /* password length         */
  4029.                       (unsigned char *)0);
  4030.                                      /* ptr to password         */
  4031.  
  4032.          if (!packet_p) exit(1);     /* If it failed, exit      */
  4033.          rc  = DPIsend_packet_to_agent(
  4034.                                      /* send OPEN packet        */
  4035.                   handle,            /* on this connection      */
  4036.                   packet_p,          /* this is the packet      */
  4037.                   DPI_PACKET_LEN(packet_p));
  4038.                                      /* and this is its length  */
  4039.          if (rc != DPI_RC_OK) exit(1);
  4040.                                      /* If it failed, exit      */
  4041.          rc  = DPIawait_packet_from_agent(
  4042.                                      /* wait for response       */
  4043.                   handle,            /* on this connection      */
  4044.                   10,                /* timeout in seconds      */
  4045.                   &packet_p,         /* receives ptr to packet  */
  4046.                   &length);          /* receives packet length  */
  4047.          if (rc != DPI_RC_OK) exit(1);
  4048.                                      /* If it failed, exit      */
  4049.          hdr_p = pDPIpacket(packet_p);
  4050.                                      /* parse DPI packet        */
  4051.          if (hdr_p == snmp_dpi_hdr_NULL_p)
  4052.                                      /* If we fail to parse it  */
  4053.             exit(1);                 /* then exit               */
  4054.          if (hdr_p->packet_type != SNMP_DPI_RESPONSE) exit(1);
  4055.          rc = hdr_p->data_u.
  4056.   resp_p->error_code;
  4057.          if (rc != SNMP_ERROR_DPI_noError) exit(1); }
  4058.   /* end of do_connect_and_open() */
  4059.  
  4060.  
  4061. ΓòÉΓòÉΓòÉ 11.3. Registering a Sub-Tree with the Agent ΓòÉΓòÉΓòÉ
  4062.  
  4063. After we have set up a connection to the agent and after we have identified 
  4064. ourselves, we must register one or more MIB sub-trees for which we want to be 
  4065. responsible to handle all SNMP requests. 
  4066.  
  4067. To do so, the subagent must create a DPI-REGISTER packet and send it to the 
  4068. agent.  The agent will then send a response to indicate success or failure of 
  4069. the register request. 
  4070.  
  4071. To create a DPI-REGISTER packet, the subagent uses a call to the 
  4072. mkDPIregister() function, which expects these parameters: 
  4073.  
  4074.      A timeout value in seconds for this sub-tree.  If you specify zero, your 
  4075.       overall timeout value that was specified in DPI-OPEN is used.  You can 
  4076.       specify a different value if you expect longer processing time for a 
  4077.       specific sub-tree. 
  4078.  
  4079.      A requested priority.  Multiple subagents may register the same sub-tree 
  4080.       at different priorities.  For example, 0 is better than 1 and so on.  The 
  4081.       agent considers the subagent with the best priority to be the active 
  4082.       subagent for the sub-tree.  If you specify -1, you are asking for the 
  4083.       best priority available.  If you specify 0, you are asking for a better 
  4084.       priority than any existing subagent may already have. 
  4085.  
  4086.      The MIB sub-tree which you want to control.  You must specify this 
  4087.       parameter with a trailing dot. 
  4088.  
  4089.      Your choice of GETBULK processing.  You can ask the agent to map a 
  4090.       GETBULK into multiple GETNEXT packets or to pass the GETBULK to you. 
  4091.  
  4092.  The function returns a pointer to a static buffer holding the DPI packet if 
  4093.  successful.  If it fails, it returns a NULL pointer. 
  4094.  
  4095.  Now we must send this DPI-REGISTER packet to the agent with the 
  4096.  DPIsend_packet_to_agent() function.  This is similar to sending the DPI_OPEN 
  4097.  packet.  We then wait for a response from the agent.  Again, we use the 
  4098.  DPIawait_packet_from_agent() function in the same way as we awaited a response 
  4099.  on the DPI-OPEN request.  Once we have received the response, we must check 
  4100.  the return code to ensure that registration was successful. 
  4101.  
  4102.  The following code example demonstrates how to register one MIB sub-tree with 
  4103.  the agent. 
  4104.  
  4105.   #include <snmp_dpi.h>             /* DPI 2.0 API definitions */
  4106.   static int handle;                /* handle has global scope */
  4107.  
  4108.   static void do_register(void)
  4109.   {
  4110.      unsigned char *packet_p;
  4111.      int            rc;
  4112.      unsigned long  length;
  4113.      snmp_dpi_hdr  *hdr_p;
  4114.  
  4115.      packet_p = mkDPIregister(          /* Make DPI register    */
  4116.                   3,                    /* timeout in seconds   */
  4117.                   0,                    /* requested priority   */
  4118.                   DPI_SIMPLE_MIB,       /* ptr to the sub-tree  */
  4119.                   DPI_BULK_NO);         /* GetBulk into GetNext */
  4120.  
  4121.      if (!packet_p) exit(1);            /* If it failed, exit   */
  4122.  
  4123.      rc  = DPIsend_packet_to_agent(     /* send REGISTER packet */
  4124.               handle,                   /* on this connection   */
  4125.               packet_p,                 /* this is the packet   */
  4126.               DPI_PACKET_LEN(packet_p));/* this is its length   */
  4127.  
  4128.      if (rc != DPI_RC_OK) exit(1);      /* If it failed, exit   */
  4129.  
  4130.      rc  = DPIawait_packet_from_agent(  /* wait for response    */
  4131.               handle,                   /* on this connection   */
  4132.               3,                        /* timeout in seconds   */
  4133.               &packet_p,                /* gets ptr to packet   */
  4134.               &length);                 /* gets packet length   */
  4135.  
  4136.      if (rc != DPI_RC_OK) exit(1);      /* If it failed, exit   */
  4137.  
  4138.      hdr_p = pDPIpacket(packet_p);      /* parse DPI packet     */
  4139.      if (hdr_p == snmp_dpi_hdr_NULL_p)  /* Failed to parse it   */
  4140.         exit(1);                        /* so exit              */
  4141.  
  4142.      if (hdr_p->packet_type != SNMP_DPI_RESPONSE) exit(1);
  4143.  
  4144.      rc = hdr_p->data_u.resp_p->error_code;
  4145.      if (rc != SNMP_ERROR_DPI_noError) exit(1);
  4146.   } /* end of do_register() */
  4147.  
  4148.  
  4149. ΓòÉΓòÉΓòÉ 11.4. Processing Requests from the Agent ΓòÉΓòÉΓòÉ
  4150.  
  4151. After we have registered our sample MIB sub-tree with the agent, we must expect 
  4152. that SNMP requests for that sub-tree will be passed for processing by us. 
  4153. Since the requests will arrive in the form of DPI packets on the connection 
  4154. that the we have established, we go into a while loop to await DPI packets from 
  4155. the agent. 
  4156.  
  4157. Since the subagent cannot know in advance which kind of packet arrives from the 
  4158. agent, we await a DPI packet (forever), then we parse the packet, check the 
  4159. packet type, and process the request based on the DPI packet type.  A call to 
  4160. pDPIpacket, which expects as parameter a pointer to the encoded/serialized DPI 
  4161. packet, returns a pointer to a DPI parse tree.  The pointer points to a 
  4162. snmp_dpi_hdr structure which looks as follows: 
  4163.  
  4164. struct snmp_dpi_hdr {
  4165.   unsigned char  proto_major;
  4166.   unsigned char  proto_version;
  4167.   unsigned char  proto_release;
  4168.   unsigned short packet_id;
  4169.   unsigned char  packet_type;
  4170.   union {
  4171.      snmp_dpi_reg_packet      *reg_p;
  4172.      snmp_dpi_ureg_packet     *ureg_p;
  4173.      snmp_dpi_get_packet      *get_p;
  4174.      snmp_dpi_next_packet     *next_p;
  4175.      snmp_dpi_next_packet     *bulk_p;
  4176.      snmp_dpi_set_packet      *set_p;
  4177.      snmp_dpi_resp_packet     *resp_p;
  4178.      snmp_dpi_trap_packet     *trap_p;
  4179.      snmp_dpi_open_packet     *open_p;
  4180.      snmp_dpi_close_packet    *close_p;
  4181.      unsigned char            *any_p;
  4182.   } data_u;
  4183. };
  4184. typedef struct snmp_dpi_hdr    snmp_dpi_hdr;
  4185. #define snmp_dpi_hdr_NULL_p    ((snmp_dpi_hdr *)0)
  4186.  
  4187. With the DPI parse tree, we decide how to process the DPI packet. The following 
  4188. code example demonstrates the high level process of a DPI subagent. 
  4189.  
  4190. #include <snmp_dpi.h>              /* DPI 2.0 API definitions */
  4191. static int handle;                 /* handle has global scope */
  4192.  
  4193. main(int argc, char *argv╤ìΓêÖ, char *envp╤ìΓêÖ)
  4194. {
  4195.   unsigned char *packet_p;
  4196.   int            rc = 0;
  4197.   unsigned long  length;
  4198.   snmp_dpi_hdr  *hdr_p;
  4199.  
  4200.   if (argc>1) {                     /* if use passed one parm */
  4201.      if (strcmp(argv╤ì1ΓêÖ,"-d")==0)   /* being -d, then we      */
  4202.          DPIdebug(2);               /* turn on DPI debugging  */
  4203.   } /* endif */                     /* which shows us things  */
  4204.  
  4205.   do_connect_and_open();            /* connect and DPI-OPEN   */
  4206.  
  4207.   do_register();                    /* register our sub-tree  */
  4208.  
  4209.   while (rc == 0) {                 /* do forever             */
  4210.    rc = DPIawait_packet_from_agent( /* wait for a DPI packet  */
  4211.            handle,                  /* on this connection     */
  4212.            -1,                      /* wait forever           */
  4213.            &packet_p,               /* receives ptr to packet */
  4214.            &length);                /* receives packet length */
  4215.  
  4216.    if (rc != DPI_RC_OK) exit(1);    /* If it failed, exit     */
  4217.  
  4218.    hdr_p = pDPIpacket(packet_p);    /* parse DPI packet       */
  4219.    if (hdr_p == snmp_dpi_hdr_NULL_p)/* If we fail to parse it */
  4220.       exit(1);                      /* then exit              */
  4221.  
  4222.    switch(hdr_p->packet_type) {     /* handle by DPI type     */
  4223.    case SNMP_DPI_GET:
  4224.      rc = do_get(hdr_p,
  4225.                  hdr_p->data_u.get_p);
  4226.      break;
  4227.    case SNMP_DPI_GETNEXT:
  4228.      rc = do_next(hdr_p,
  4229.                   hdr_p->data_u.next_p);
  4230.      break;
  4231.  
  4232.  
  4233.    case SNMP_DPI_SET:
  4234.    case SNMP_DPI_COMMIT:
  4235.    case SNMP_DPI_UNDO:
  4236.      rc = do_set(hdr_p,
  4237.                  hdr_p->data_u.set_p);
  4238.      break;
  4239.    case SNMP_DPI_CLOSE:
  4240.      rc = do_close(hdr_p,
  4241.                    hdr_p->data_u.close_p);
  4242.      break;
  4243.    case SNMP_DPI_UNREGISTER:
  4244.      rc = do_unreg(hdr_p,
  4245.                    hdr_p->data_u.ureg_p);
  4246.      break;
  4247.    default:
  4248.      printf("Unexpected DPI packet type %d\n",
  4249.             hdr_p->packet_type);
  4250.      rc = -1;
  4251.    } /* endswitch */
  4252.    if (rc) exit(1);
  4253.   } /* endwhile */
  4254.  
  4255.   return(0);
  4256. } /* end of main() */
  4257.  
  4258.  
  4259. ΓòÉΓòÉΓòÉ 11.5. Processing a GET Request ΓòÉΓòÉΓòÉ
  4260.  
  4261. When the DPI packet is parsed, the snmp_dpi_hdr structure will show in the 
  4262. packet_type that this is a SNMP_DPI_GET packet.  In that case, the packet_body 
  4263. contains a pointer to a GET-varBind, which is represented in an 
  4264. snmp_dpi_get_packet structure: 
  4265.  
  4266. struct dpi_get_packet {
  4267.   char                   *object_p;   /* ptr to OIDstring     */
  4268.   char                   *group_p;    /* ptr to sub-tree      */
  4269.   char                   *instance_p; /* ptr to rest of OID   */
  4270.   struct dpi_get_packet  *next_p;     /* ptr to next in chain */
  4271. };
  4272. typedef struct dpi_get_packet       snmp_dpi_get_packet;
  4273. #define snmp_dpi_get_packet_NULL_p  ((snmp_dpi_get_packet *)0)
  4274.  
  4275. Assuming we have registered example sub-tree 1.3.6.1.4.1.2.2.1.5 and a GET 
  4276. request comes in for one variable 1.3.6.1.4.1.2.2.1.5.1.0 so that it is object 
  4277. 1 instance 0 in our sub-tree, the fields in the snmp_dpi_get_packet would have 
  4278. pointers to: 
  4279.  
  4280.   object_p   ->  "1.3.6.1.4.1.2.2.1.5.1.0"
  4281.   group_p    ->  "1.3.6.1.4.1.2.2.1.5."
  4282.   instance_p ->  "1.0"
  4283.   next_p     ->  snmp_dpi_get_packet_NULL_p
  4284.  
  4285. If there are multiple varBinds in a GET request, each one is represented in a 
  4286. snmp_dpi_get_packet structure and all the snmp_dpi_get_packet structures are 
  4287. chained via the next pointer.  As long as the next pointer is not the 
  4288. snmp_dpi_get_packet_NULL_p pointer, there are more varBinds in the list. 
  4289.  
  4290. Now we can analyze the varBind structure for whatever checking we want to do. 
  4291. Once we are ready to make a response that contains the value of the variable, 
  4292. we prepare a SET-varBind which is represented in an snmp_dpi_set_packet 
  4293. structure: 
  4294.  
  4295. struct dpi_set_packet {
  4296.   char                   *object_p;   /* ptr to OIDstring     */
  4297.   char                   *group_p;    /* ptr to sub-tree      */
  4298.   char                   *instance_p; /* ptr to rest of OID   */
  4299.   unsigned char           value_type; /* SNMP_TYPE_xxxx       */
  4300.   unsigned short          value_len;  /* value length         */
  4301.   char                   *value_p;    /* ptr to value itself  */
  4302.   struct dpi_set_packet  *next_p;     /* ptr to next in chain */
  4303. };
  4304. typedef struct dpi_set_packet       snmp_dpi_set_packet;
  4305. #define snmp_dpi_set_packet_NULL_p  ((snmp_dpi_set_packet *)0)
  4306.  
  4307. We can use the mkDPIset() function to prepare such a structure. This function 
  4308. expects the following parameters: 
  4309.  
  4310.      A pointer to an existing snmp_dpi_set_packet structure if the new varBind 
  4311.       must be added to an existing chain of varBinds.  If this is the first or 
  4312.       the only varBind in the chain, pass the snmp_dpi_set_packet_NULL_p 
  4313.       pointer to indicate this. 
  4314.  
  4315.      A pointer to the sub-tree that we registered. 
  4316.  
  4317.      A pointer to the rest of the OID; in other words, the piece that follows 
  4318.       the sub-tree. 
  4319.  
  4320.      The value type of the value to be bound to the variable name.  This is 
  4321.       must be one of the SNMP_TYPE_xxxx values as defined in the snmp_dpi.h 
  4322.       include file. 
  4323.  
  4324.      The length of the value for integer type values.  This must be a length 
  4325.       of 4.  So we always work with 32-bit signed or unsigned integers except 
  4326.       for the Counter64 type.  For the Counter64 type, we must point to a 
  4327.       snmp_dpi_u64 structure and pass the length of that structure. 
  4328.  
  4329.      A pointer to the value. 
  4330.  
  4331.  Memory for the varBind is dynamically allocated and the data itself is copied. 
  4332.  So upon return we can dispose of our own pointers and allocated memory as we 
  4333.  please.  If the call is successful, a pointer is returned as follows: 
  4334.  
  4335.      To a new snmp_dpi_set_packet if it is the first or only varBind. 
  4336.  
  4337.      To the existing snmp_dpi_set_packet that we passed on the call.  In this 
  4338.       case, the new packed has been chained to the end of the varBind list. 
  4339.  
  4340.  If the mkDPIset() call fails, a NULL pointer is returned. 
  4341.  
  4342.  Once we have prepared the SET-varBind data, we can create a DPI RESPONSE 
  4343.  packet using the mkDPIresponse() function which expects these parameters: 
  4344.  
  4345.      A pointer to an snmp_dpi_hdr.  We should use the header of the parsed 
  4346.       incoming packet.  It is used to copy the packet_id from the request into 
  4347.       the response, such that the agent can correlate the response to a 
  4348.       request. 
  4349.  
  4350.      A return code which is an SNMP error code.  If successful, this should be 
  4351.       SNMP_ERROR_noError (value zero).  If failure, it must be one of the 
  4352.       SNMP_ERROR_xxxx values as defined in the snmp_dpi.h include file. 
  4353.  
  4354.       A request for a non-existing object or instance is not considered an 
  4355.       error.  Instead, we must pass a value type of SNMP_TYPE_noSuchObject or 
  4356.       SNMP_TYPE_noSuchInstance respectively.  These two value types have an 
  4357.       implicit value of NULL, so we can pass a zero length and a NULL pointer 
  4358.       for the value in this case. 
  4359.  
  4360.      The index of the varBind in error starts counting at 1.  Pass zero if no 
  4361.       error occurred, or pass the proper index of the first varBind for which 
  4362.       an error was detected. 
  4363.  
  4364.      A pointer to a chain of snmp_dpi_set_packets (varBinds) to be returned as 
  4365.       response to the GET request.  If an error was detected, an 
  4366.       snmp_dpi_set_packet_NULL_p pointer may be passed. 
  4367.  
  4368.  The following code example returns a response.  We assume that there are no 
  4369.  errors in the request, but proper code should do the checking for that.  For 
  4370.  instance, we return a noSuchInstance if the instance is not exactly what we 
  4371.  expect and a noSuchObject if the object instance_ID is greater than 3, for 
  4372.  example 4.0.  However, there might be no instance_ID at all and we should 
  4373.  check for that too. 
  4374.  
  4375.   static int do_get(snmp_dpi_hdr *hdr_p,
  4376.                     snmp_dpi_get_packet *pack_p)
  4377.   {
  4378.     unsigned char       *packet_p;
  4379.     int                  rc;
  4380.     snmp_dpi_set_packet *varBind_p;
  4381.  
  4382.     varBind_p =                        /* init the varBind chain*/
  4383.        snmp_dpi_set_packet_NULL_p;     /* to a NULL pointer     */
  4384.  
  4385.     if (pack_p->instance_p &&
  4386.         (strcmp(pack_p->instance_p,"1.0") == 0))
  4387.     {
  4388.       varBind_p = mkDPIset(            /* Make DPI set packet   */
  4389.                   varBind_p,           /* ptr to varBind chain  */
  4390.                   pack_p->group_p,     /* ptr to sub-tree       */
  4391.                   pack_p->instance_p,  /* ptr to rest of OID    */
  4392.                   SNMP_TYPE_Integer32, /* value type Integer 32 */
  4393.                   sizeof(value1),      /* length of value       */
  4394.                   &value1);            /* ptr to value          */
  4395.     } else if (pack_p->instance_p &&
  4396.         (strcmp(pack_p->instance_p,"2.0") == 0))
  4397.     {
  4398.       varBind_p = mkDPIset(               /* Make DPI set packet*/
  4399.                   varBind_p,              /* ptr to varBindchain*/
  4400.                   pack_p->group_p,        /* ptr to sub-tree    */
  4401.                   pack_p->instance_p,     /* ptr to rest of OID */
  4402.                   SNMP_TYPE_DisplayString,/* value type         */
  4403.                   strlen(value2_p),       /* length of value    */
  4404.                   value2_p);              /* ptr to value       */
  4405.     } else if (pack_p->instance_p &&
  4406.         (strcmp(pack_p->instance_p,"3.0") == 0))
  4407.     {
  4408.       varBind_p = mkDPIset(               /* Make DPI set packet*/
  4409.                   varBind_p,              /* ptr to varBindchain*/
  4410.                   pack_p->group_p,        /* ptr to sub-tree    */
  4411.                   pack_p->instance_p,     /* ptr to rest of OID */
  4412.                   SNMP_TYPE_Counter32,    /* value type         */
  4413.                   sizeof(value3),         /* length of value    */
  4414.                   &value3);               /* ptr to value       */
  4415.     } else if (pack_p->instance_p &&
  4416.         (strcmp(pack_p->instance_p,"3")>0))
  4417.     {
  4418.       varBind_p = mkDPIset(               /* Make DPI set packet*/
  4419.                  varBind_p,               /* ptr to varBindchain*/
  4420.                  pack_p->group_p,         /* ptr to sub-tree    */
  4421.                  pack_p->instance_p,      /* ptr to rest of OID */
  4422.                  SNMP_TYPE_noSuchObject,  /* value type         */
  4423.                  0L,                      /* length of value    */
  4424.                  (unsigned char *)0);     /* ptr to value       */
  4425.     } else {
  4426.       varBind_p = mkDPIset(               /* Make DPI set packet*/
  4427.                  varBind_p,               /* ptr to varBindchain*/
  4428.                  pack_p->group_p,         /* ptr to sub-tree    */
  4429.                  pack_p->instance_p,      /* ptr to rest of OID */
  4430.                  SNMP_TYPE_noSuchInstance,/* value type         */
  4431.                  0L,                      /* length of value    */
  4432.                  (unsigned char *)0);     /* ptr to value       */
  4433.     } /* endif */
  4434.  
  4435.     if (!varBind_p) return(-1);        /* If it failed, return  */
  4436.  
  4437.     packet_p = mkDPIresponse(          /* Make DPIresponse pack */
  4438.                  hdr_p,                /* ptr parsed request    */
  4439.                  SNMP_ERROR_noError,   /* all is OK, no error   */
  4440.                  0L,                   /* index zero, no error  */
  4441.                  varBind_p);           /* varBind response data */
  4442.  
  4443.     if (!packet_p) return(-1);         /* If it failed, return  */
  4444.  
  4445.     rc  = DPIsend_packet_to_agent(     /* send RESPONSE packet  */
  4446.              handle,                   /* on this connection    */
  4447.              packet_p,                 /* this is the packet    */
  4448.              DPI_PACKET_LEN(packet_p));/* and this is its length*/
  4449.  
  4450.     return(rc);                        /* return retcode        */
  4451.   } /* end of do_get() */
  4452.  
  4453.  
  4454. ΓòÉΓòÉΓòÉ 11.6. Processing a GETNEXT Request ΓòÉΓòÉΓòÉ
  4455.  
  4456. When a DPI packet is parsed, the snmp_dpi_hdr structure shows in the 
  4457. packet_type that this is a SNMP_DPI_GETNEXT packet, and so the packet_body 
  4458. contains a pointer to a GETNEXT-varBind, which is represented in an 
  4459. snmp_dpi_next_packet structure: 
  4460.  
  4461. struct dpi_next_packet {
  4462.   char                   *object_p;    /* ptr to OIDstring    */
  4463.   char                   *group_p;     /* ptr to sub-tree     */
  4464.   char                   *instance_p;  /* ptr to rest of OID  */
  4465.   struct dpi_next_packet *next_p;      /* ptr to next in chain*/
  4466. };
  4467. typedef struct dpi_next_packet      snmp_dpi_next_packet;
  4468. #define snmp_dpi_next_packet_NULL_p ((snmp_dpi_next_packet *)0)
  4469.  
  4470. In the interest of simplicity and easier understanding we will discuss the 
  4471. GETNEXT for a scalar object, which only has one instance. For columnar objects, 
  4472. which may have multiple instances, the process is more complex. However, the 
  4473. DPI subagent programmer should be able to handle that once the basics of 
  4474. GETNEXT processing in a DPI subagent is understood. 
  4475.  
  4476. Assuming we have registered example sub-tree dpiSimpleMIB and a GETNEXT arrives 
  4477. for one variable, dpiSimpleInteger.0, so that is object 1 instance 0 in our 
  4478. sub-tree, the fields in the snmp_dpi_get_packet structure would have pointers 
  4479. to: 
  4480.  
  4481. object_p    ->  "1.3.6.1.4.1.2.2.1.5.1.0"
  4482. group_p     ->  "1.3.6.1.4.1.2.2.1.5."
  4483. instance_p  ->  "1.0"
  4484. next_p      ->  snmp_dpi_next_packet_NULL_p
  4485.  
  4486. If there are multiple varBinds in a GETNEXT request, each one is represented in 
  4487. a snmp_dpi_get_packet structure and all the snmp_dpi_get_packet structures are 
  4488. chained via the next pointer.  As long as the next pointer is not the 
  4489. snmp_dpi_next_packet_NULL_p pointer, there are more varBinds in the list. 
  4490.  
  4491. Now we can analyze the varBind structure for whatever checking we want to do. 
  4492. We must find out which OID is the one that lexicographically follows the one in 
  4493. the request.  It is that OID with its value that we must return as a response. 
  4494. Therefore, we must now also set the proper OID in the response.  Once we are 
  4495. ready to make a response that contains the new OID and the value of that 
  4496. variable, we must prepare a SET-varBind which is represented in an 
  4497. snmp_dpi_set_packet: 
  4498.  
  4499. struct dpi_set_packet {
  4500.   char                   *object_p;   /* ptr to OIDstring     */
  4501.   char                   *group_p;    /* ptr to sub-tree      */
  4502.   char                   *instance_p; /* ptr to rest of OID   */
  4503.   unsigned char           value_type; /* SNMP_TYPE_xxxx       */
  4504.   unsigned short          value_len;  /* value length         */
  4505.   char                   *value_p;    /* ptr to value itself  */
  4506.   struct dpi_set_packet  *next_p;     /* ptr to next in chain */
  4507. };
  4508. typedef struct dpi_set_packet        snmp_dpi_set_packet;
  4509. #define snmp_dpi_set_packet_NULL_p   ((snmp_dpi_set_packet *)0)
  4510.  
  4511. We can use the mkDPIset() function to prepare such a structure. This function 
  4512. expects the following parameters: 
  4513.  
  4514.      A pointer to an existing snmp_dpi_set_packet structure if the new varBind 
  4515.       must be added to an existing chain of varBinds.  If this is the first or 
  4516.       only varBind in the chain, we pass the snmp_dpi_set_packet_NULL_p pointer 
  4517.       to indicate this. 
  4518.  
  4519.      A pointer to the sub-tree that we registered. 
  4520.  
  4521.      A pointer to the rest of the OID, in other words the piece that follows 
  4522.       the sub-tree. 
  4523.  
  4524.      The value type of the value to be bound to the variable name.  This is 
  4525.       must be one of the SNMP_TYPE_xxxx values as defined in the snmp_dpi.h 
  4526.       include file. 
  4527.  
  4528.      The length of the value for integer type values.  This must be a length 
  4529.       of 4.  So we always work with 32-bit signed or unsigned integers except 
  4530.       for the Counter64 type.  For Counter 64 type, we must point to a 
  4531.       snmp_dpi_u64 structure and pass the length of that structure. 
  4532.  
  4533.      A pointer to the value. 
  4534.  
  4535.  Memory for the varBind is dynamically allocated and the data itself is copied. 
  4536.  Upon return, we can dispose of our own pointers and allocated memory as we 
  4537.  please.  If the call is successful, a pointer is returned as follows: 
  4538.  
  4539.      A new snmp_dpi_set_packet if it is the first or only varBind. 
  4540.  
  4541.      The existing snmp_dpi_set_packet that we passed on the call.  In this 
  4542.       case, the new packed has been chained to the end of the varBind list. 
  4543.  
  4544.  If the mkDPIset() call fails, a NULL pointer is returned. 
  4545.  
  4546.  Once we have prepared the SET-varBind data, we can create a DPI RESPONSE 
  4547.  packet using the mkDPIresponse() function, which expects these parameters: 
  4548.  
  4549.      A pointer to an snmp_dpi_hdr.  We should use the header of the parsed 
  4550.       incoming packet.  It is used to copy the packet_id from the request into 
  4551.       the response, such that the agent can correlate the response to a 
  4552.       request. 
  4553.  
  4554.      A return code which is an SNMP error code.  If successful, this should be 
  4555.       SNMP_ERROR_noError (value zero).  If failure, it must be one of the 
  4556.       SNMP_ERROR_xxxx values as defined in the snmp_dpi.h include file. 
  4557.  
  4558.       A request for a non-existing object or instance is not considered an 
  4559.       error.  Instead, we must pass the OID and value of the first OID that 
  4560.       lexicographically follows the non-existing object and/or instance. 
  4561.  
  4562.       Reaching the end of our sub-tree is not considered an error.  For 
  4563.       example, if there is no NEXT OID, this is not an error.  In this 
  4564.       situation we must return the original OID as received in the request and 
  4565.       a value_type of SNMP_TYPE_endOfMibView.  This value_type has an implicit 
  4566.       value of NULL, so we can pass a zero length and a NULL pointer for the 
  4567.       value. 
  4568.  
  4569.      The index of the first varBind in error starts counting at 1.  Pass zero 
  4570.       if no error occurred, or pass the proper index of the first varBind for 
  4571.       which an error was detected. 
  4572.  
  4573.      A pointer to a chain of snmp_dpi_set_packet(s) (varBinds) to be returned 
  4574.       as response to the GETNEXT request.  If an error was detected, an 
  4575.       snmp_dpi_set_packet_NULL_p pointer may be passed. 
  4576.  
  4577.  The following code example returns a response.  We assume that there are no 
  4578.  errors in the request, but proper code should do the checking for that.  We do 
  4579.  proper checking for lexicographic next object, but we do no checking for 
  4580.  ULONG_MAX, or making sure that the instance ID is indeed valid (digits and 
  4581.  dots).  If we get to the end of our dpiSimpleMIB, we must return an 
  4582.  endOfMibView as defined by the SNMP Version 2 rules. 
  4583.  
  4584.   static int do_next(snmp_dpi_hdr *hdr_p,
  4585.                      snmp_dpi_next_packet *pack_p)
  4586.   {
  4587.     unsigned char       *packet_p;
  4588.     int                  rc;
  4589.     unsigned long        subid;        /* subid is unsigned     */
  4590.     unsigned long        instance;     /* same with instance    */
  4591.     char                *cp;
  4592.     snmp_dpi_set_packet *varBind_p;
  4593.  
  4594.     varBind_p =                        /* init the varBind chain*/
  4595.        snmp_dpi_set_packet_NULL_p;     /* to a NULL pointer     */
  4596.  
  4597.     if (pack_p->instance_p) {          /* we have an instance ID*/
  4598.        cp = pack_p->instance_p;        /* pick up ptr           */
  4599.        subid = strtoul(cp, &cp, 10);   /* convert subid (object)*/
  4600.        if (*cp == '.') {               /* followed by a dot ?   */
  4601.           cp++;                        /* point after it if yes */
  4602.           instance=strtoul(cp,&cp,10); /* convert real instance */
  4603.                                        /* not that we need it,we*/
  4604.           subid++;                     /* only have instance 0, */
  4605.                                        /* so NEXT is next object*/
  4606.           instance = 0;                /* and always instance 0 */
  4607.        } else {                        /* no real instance      */
  4608.           instance = 0;                /* passed, so we use 0   */
  4609.           if (subid == 0) subid++;     /* if object 0, subid 1  */
  4610.        } /* endif */
  4611.     } else {                           /* no instance ID passed */
  4612.        subid = 1;                      /* so do first object    */
  4613.        instance = 0;                   /* 0 is all we have      */
  4614.     } /* endif */
  4615.  
  4616.     /* we have set subid and instance such that we can basically*/
  4617.     /* process the request as a GET now. Actually, we don't even*/
  4618.     /* need instance, because all out object instances are zero.*/
  4619.  
  4620.     if (instance != 0) printf("Strange instance: %lu\n",instance);
  4621.  
  4622.     switch (subid) {
  4623.     case 1:
  4624.       varBind_p = mkDPIset(            /* Make DPI set packet   */
  4625.                   varBind_p,           /* ptr to varBind chain  */
  4626.                   pack_p->group_p,     /* ptr to sub-tree       */
  4627.                   DPI_SIMPLE_INTEGER,  /* ptr to rest of OID    */
  4628.                   SNMP_TYPE_Integer32, /* value type Integer 32 */
  4629.                   sizeof(value1),      /* length of value       */
  4630.                   &value1);            /* ptr to value          */
  4631.       break;
  4632.     case 2:
  4633.       varBind_p = mkDPIset(               /* Make DPI set packet*/
  4634.                   varBind_p,              /* ptr to varBindchain*/
  4635.                   pack_p->group_p,        /* ptr to sub-tree    */
  4636.                   DPI_SIMPLE_STRING,      /* ptr to rest of OID */
  4637.                   SNMP_TYPE_DisplayString,/* value type         */
  4638.                   strlen(value2_p),       /* length of value    */
  4639.                   value2_p);              /* ptr to value       */
  4640.       break;
  4641.     case 3:
  4642.       varBind_p = mkDPIset(               /* Make DPI set packet*/
  4643.                   varBind_p,              /* ptr to varBindchain*/
  4644.                   pack_p->group_p,        /* ptr to sub-tree    */
  4645.                   DPI_SIMPLE_COUNTER32,   /* ptr to rest of OID */
  4646.                   SNMP_TYPE_Counter32,    /* value type         */
  4647.                   sizeof(value3),         /* length of value    */
  4648.                   &value3);               /* ptr to value       */
  4649.       break;
  4650.     case 4:                               /*                *Apr23*/
  4651.       varBind_p = mkDPIset(               /* Make DPI set packet  */
  4652.                   varBind_p,              /* ptr to varBind chain */
  4653.                   pack_p->group_p,        /* ptr to sub-tree      */
  4654.                   DPI_SIMPLE_COUNTER64,   /* ptr to rest of OID   */
  4655.                   SNMP_TYPE_Counter64,    /* value type           */
  4656.                   sizeof(value4),         /* length of value      */
  4657.                   &value4);               /* ptr to value         */
  4658.       break;                              /*                *Apr23*/
  4659.     default:
  4660.       varBind_p = mkDPIset(               /* Make DPI set packet*/
  4661.                   varBind_p,              /* ptr to varBindchain*/
  4662.                   pack_p->group_p,        /* ptr to sub-tree    */
  4663.                   pack_p->instance_p,     /* ptr to rest of OID */
  4664.                   SNMP_TYPE_endOfMibView, /* value type         */
  4665.                   0L,                     /* length of value    */
  4666.                   (unsigned char *)0);    /* ptr to value       */
  4667.       break;
  4668.     } /* endswitch */
  4669.  
  4670.     if (!varBind_p) return(-1);        /* If it failed, return  */
  4671.  
  4672.     packet_p = mkDPIresponse(          /* Make DPIresponse pack */
  4673.                  hdr_p,                /* ptr parsed request    */
  4674.                  SNMP_ERROR_noError,   /* all is OK, no error   */
  4675.                  0L,                   /* index zero, no error  */
  4676.                  varBind_p);           /* varBind response data */
  4677.  
  4678.     if (!packet_p) return(-1);         /* If it failed, return  */
  4679.  
  4680.     rc  = DPIsend_packet_to_agent(     /* send RESPONSE packet  */
  4681.              handle,                   /* on this connection    */
  4682.              packet_p,                 /* this is the packet    */
  4683.              DPI_PACKET_LEN(packet_p));/* and this is its length*/
  4684.  
  4685.     return(rc);                        /* return retcode        */
  4686.   } /* end of do_next() */
  4687.  
  4688.  
  4689. ΓòÉΓòÉΓòÉ 11.7. Processing a SET/COMMIT/UNDO Request ΓòÉΓòÉΓòÉ
  4690.  
  4691. These three requests can come in one of these sequences: 
  4692.  
  4693.      SET, COMMIT 
  4694.      SET, UNDO 
  4695.      SET, COMMIT, UNDO 
  4696.  
  4697.  The normal sequence is SET and then COMMIT.  When we receive a SET request, we 
  4698.  must make preparations to accept the new value.  For example, check that it is 
  4699.  for an existing object and instance, check the value type and contents to be 
  4700.  valid, allocate memory, but we must not yet make the change. 
  4701.  
  4702.  If there are no SET errors, the next request we receive will be a COMMIT 
  4703.  request.  It is then that we must make the change, but we must also keep 
  4704.  enough information such that we can UNDO the change later if we get a 
  4705.  subsequent UNDO request.  The latter may happen if the agent discovers any 
  4706.  errors with other subagents while processing requests that belong to the same 
  4707.  original SNMP SET packet.  All the varBinds in the same SNMP request PDU must 
  4708.  be processed "as if atomic". 
  4709.  
  4710.  When the DPI packet is parsed, the snmp_dpi_hdr structure shows in the 
  4711.  packet_type that this is an SNMP_DPI_SET, SNMP_DPI_COMMIT, or SNMP_DPI_UNDO 
  4712.  packet.  In that case, the packet_body contains a pointer to a SET-varBind, 
  4713.  represented in an snmp_dpi_get_packet structure.  COMMIT and UNDO have same 
  4714.  varBind data as SET upon which they follow: 
  4715.  
  4716.   struct dpi_set_packet {
  4717.     char                   *object_p;   /* ptr to OIDstring     */
  4718.     char                   *group_p;    /* ptr to sub-tree      */
  4719.     char                   *instance_p; /* ptr to rest of OID   */
  4720.     unsigned char           value_type; /* SNMP_TYPE_xxxx       */
  4721.     unsigned short          value_len;  /* value length         */
  4722.     char                   *value_p;    /* ptr to value itself  */
  4723.     struct dpi_set_packet  *next_p;     /* ptr to next in chain */
  4724.   };
  4725.   typedef struct dpi_set_packet        snmp_dpi_set_packet;
  4726.   #define snmp_dpi_set_packet_NULL_p   ((snmp_dpi_set_packet *)0)
  4727.  
  4728.  Assuming we have registered example sub-tree dpiSimpleMIB and a GET request 
  4729.  comes in for one variable dpiSimpleString.0 so that is object 1 instance 0 in 
  4730.  our sub-tree, and also assuming that the agent knows about our compiled 
  4731.  dpiSimpleMIB so that it knows this is a DisplayString as opposed to just an 
  4732.  arbitrary OCTET_STRING, the pointers in the snmp_dpi_set_packet structure 
  4733.  would have pointers and values like: 
  4734.  
  4735.   object_p    ->  "1.3.6.1.4.1.2.2.1.5.2.0"
  4736.   group_p     ->  "1.3.6.1.4.1.2.2.1.5."
  4737.   instance_p  ->  "2.0"
  4738.   value_type  ->  SNMP_TYPE_DisplayString
  4739.   value_len   ->  8
  4740.   value_p     ->  pointer to the value to be set
  4741.   next_p      ->  snmp_dpi_get_packet_NULL_p
  4742.  
  4743.  If there are multiple varBinds in a SET request, each one is represented in a 
  4744.  snmp_dpi_set_packet structure and all the snmp_dpi_set_packet structures are 
  4745.  chained via the next pointer.  As long as the next pointer is not the 
  4746.  snmp_dpi_set_packet_NULL_p pointer, there are more varBinds in the list. 
  4747.  
  4748.  Now we can analyze the varBind structure for whatever checking we want to do. 
  4749.  Once we are ready to make a response that contains the value of the variable, 
  4750.  we may prepare a new SET-varBind.  However, by definition, the response to a 
  4751.  successful SET is exactly the same as the SET request.  So there is no need to 
  4752.  return any varBinds. A response with SNMP_ERROR_noError and an index of zero 
  4753.  will do.  If there is an error, a response with the SNMP_ERROR_xxxx error code 
  4754.  and an index pointing to the varBind in error (counting starts at 1) will do. 
  4755.  
  4756.  The following code example returns a response.  We assume that there are no 
  4757.  errors in the request, but proper code should do the checking for that.  We 
  4758.  also do not check if the varBind in the COMMIT and/or UNDO is the same as that 
  4759.  in the SET request.  A proper agent would make sure that is the case, but a 
  4760.  proper subagent may want to verify that for itself.  We only do one check that 
  4761.  this is dpiSimpleString.0, and if it is not, we return a noCreation.  This may 
  4762.  not be correct, the mainline does not even return a response. 
  4763.  
  4764.   static int do_set(snmp_dpi_hdr *hdr_p, snmp_dpi_set_packet *pack_p)
  4765.   {
  4766.          unsigned char       *packet_p;
  4767.          int                  rc;
  4768.          int                  index       = 0;
  4769.          int                  error       = SNMP_ERROR_noError;
  4770.          snmp_dpi_set_packet *varBind_p;
  4771.  
  4772.          varBind_p =                        /* init the varBind chain  */
  4773.             snmp_dpi_set_packet_NULL_p;     /* to a NULL pointer       */
  4774.  
  4775.          if (!pack_p->instance_p ||
  4776.              (strcmp(pack_p->instance_p,"2.0") != 0))
  4777.          {
  4778.  
  4779.             if (pack_p->instance_p &&
  4780.                (strncmp(pack_p->instance_p,"1.",2) == 0))
  4781.             {
  4782.                error = SNMP_ERROR_notWritable;
  4783.             } else if (pack_p->instance_p &&
  4784.                (strncmp(pack_p->instance_p,"2.",2) == 0))
  4785.             {
  4786.                error = SNMP_ERROR_noCreation;
  4787.             } else if (pack_p->instance_p &&
  4788.                (strncmp(pack_p->instance_p,"3.",2) == 0))
  4789.             {
  4790.                error = SNMP_ERROR_notWritable;
  4791.             } else {
  4792.                error = SNMP_ERROR_noCreation;
  4793.             } /* endif */
  4794.  
  4795.             packet_p = mkDPIresponse(       /* Make DPIresponse packet */
  4796.                       hdr_p,                /* ptr parsed request      */
  4797.                       error,                /* all is OK, no error     */
  4798.                       1,                    /* index is 1, 1st varBind */
  4799.                       varBind_p);           /* varBind response data   */
  4800.  
  4801.             if (!packet_p) return(-1);      /* If it failed, return    */
  4802.  
  4803.             rc  = DPIsend_packet_to_agent(  /* send RESPONSE packet    */
  4804.                   handle,                   /* on this connection      */
  4805.                   packet_p,                 /* this is the packet      */
  4806.                   DPI_PACKET_LEN(packet_p));/* and this is its length  */
  4807.  
  4808.             return(rc);                     /* return retcode          */
  4809.          }
  4810.  
  4811.          switch (hdr_p->packet_type) {
  4812.          case SNMP_DPI_SET:
  4813.            if ((pack_p->value_type != SNMP_TYPE_DisplayString) &&
  4814.                (pack_p->value_type != SNMP_TYPE_OCTET_STRING))
  4815.            {  /* check octet string in case agent has no compiled MIB  */
  4816.               error = SNMP_ERROR_wrongType;
  4817.               break;                        /* from switch             */
  4818.            } /* endif */
  4819.            if (new_val_p) free(new_val_p);  /* free these memory areas */
  4820.            if (old_val_p) free(old_val_p);  /* if we allocated any     */
  4821.            new_val_p   = (char *)0;
  4822.            old_val_p   = (char *)0;
  4823.            new_val_len = 0;
  4824.            old_val_len = 0;
  4825.  
  4826.            new_val_p =                      /* allocate memory for     */
  4827.                malloc(pack_p->value_len);   /* new value to set        */
  4828.            if (new_val_p) {                 /* If success, then also   */
  4829.               memcpy(new_val_p,             /* copy new value to our   */
  4830.                      pack_p->value_p,       /* own and newly allocated */
  4831.                      pack_p->value_len);    /* memory area.            */
  4832.               new_val_len = pack_p->value_len;
  4833.            } else {                         /* Else failed to malloc,  */
  4834.               error = SNMP_ERROR_genErr;    /* so that is a genErr     */
  4835.               index = 1;                    /* at first varBind        */
  4836.            } /* endif */
  4837.            break;
  4838.          case SNMP_DPI_COMMIT:
  4839.            old_val_p = cur_val_p;           /* save old value for undo */
  4840.            cur_val_p = new_val_p;           /* make new value current  */
  4841.            new_val_p = (char *)0;           /* keep only 1 ptr around  */
  4842.            old_val_len = cur_val_len;       /* and keep lengths correct*/
  4843.            cur_val_len = new_val_len;
  4844.            new_val_len = 0;
  4845.            /* may need to convert from ASCII to native if OCTET_STRING */
  4846.            break;
  4847.          case SNMP_DPI_UNDO:
  4848.            if (new_val_p) {                 /* free allocated memory   */
  4849.               free(new_val_p);
  4850.               new_val_p   = (char *)0;
  4851.               new_val_len = 0;
  4852.            } /* endif */
  4853.            if (old_val_p) {
  4854.               if (cur_val_p) free(cur_val_p);
  4855.               cur_val_p   = old_val_p;      /* reset to old value      */
  4856.               cur_val_len = old_val_len;
  4857.               old_val_p   = (char *)0;
  4858.               old_val_len = 0;
  4859.            } /* endif */
  4860.            break;
  4861.          } /* endswitch */
  4862.  
  4863.          packet_p = mkDPIresponse(          /* Make DPIresponse packet */
  4864.                       hdr_p,                /* ptr parsed request      */
  4865.                       error,                /* all is OK, no error     */
  4866.                       index,                /* index is zero, no error */
  4867.                       varBind_p);           /* varBind response data   */
  4868.  
  4869.          if (!packet_p) return(-1);         /* If it failed, return    */
  4870.  
  4871.          rc  = DPIsend_packet_to_agent(     /* send RESPONSE packet    */
  4872.                   handle,                   /* on this connection      */
  4873.                   packet_p,                 /* this is the packet      */
  4874.                   DPI_PACKET_LEN(packet_p));/* and this is its length  */
  4875.  
  4876.          return(rc);                        /* return retcode          */
  4877.   } /* end of do_set() */
  4878.  
  4879.  
  4880. ΓòÉΓòÉΓòÉ 11.8. Processing an UNREGISTER Request ΓòÉΓòÉΓòÉ
  4881.  
  4882. An agent can send an UNREGISTER packet if some other subagent does a register 
  4883. for the same sub-tree at a higher priority.  An agent can also send an 
  4884. UNREGISTER if, for example, an SNMP manager tells it to "invalidate" the 
  4885. subagent connection or the registered sub-tree. 
  4886.  
  4887. Here is an example of how to handle such a packet. 
  4888.  
  4889. #include <snmp_dpi.h>          /* DPI 2.0 API definitions */
  4890.  
  4891. static int do_unreg(snmp_dpi_hdr *hdr_p,
  4892.                     snmp_dpi_ureg_packet *pack_p)
  4893. {
  4894.   printf("DPI UNREGISTER received from agent, reason=%d\n",
  4895.           pack_p->reason_code);
  4896.   printf("    sub-tree=%s\n",pack_p->group_p);
  4897.   DPIdisconnect_from_agent(handle);
  4898.   return(-1); /* causes exit in main loop */
  4899. } /* end of do_unreg() */
  4900.  
  4901.  
  4902. ΓòÉΓòÉΓòÉ 11.9. Processing a CLOSE Request ΓòÉΓòÉΓòÉ
  4903.  
  4904. An agent can send a CLOSE packet if it encounters an error or for some other 
  4905. reason.  It can also do so if an SNMP MANAGER tells it to "invalidate" the 
  4906. subagent connection. 
  4907.  
  4908. Here is an example of how to handle such a packet. 
  4909.  
  4910. #include <snmp_dpi.h>           /* DPI 2.0 API definitions */
  4911.  
  4912. static int do_close(snmp_dpi_hdr *hdr_p,
  4913.                     snmp_dpi_close_packet *pack_p)
  4914. {
  4915.   printf("DPI CLOSE received from agent, reason=%d\n",
  4916.          pack_p->reason_code);
  4917.  
  4918.   DPIdisconnect_from_agent(handle);
  4919.   return(-1); /* causes exit in main loop */
  4920. } /* end of do_close() */
  4921.  
  4922.  
  4923. ΓòÉΓòÉΓòÉ 11.10. Generating a TRAP ΓòÉΓòÉΓòÉ
  4924.  
  4925. A trap can be issued at any time after a DPI OPEN was successful. To do so, you 
  4926. must create a trap packet and send it to the agent.  With the TRAP, you can 
  4927. pass all sorts of varBinds if you want.  In this example, we pass two varBinds 
  4928. one with integer data and one with an octet string.  You can also pass an 
  4929. Enterprise ID, but with DPI 2.0, the agent will use your subagent ID as the 
  4930. enterprise ID if you do not pass one with the trap.  In most cases that will 
  4931. probably be fine. 
  4932.  
  4933. We must first prepare a varBind list chain that contains the two variables that 
  4934. we want to pass along with the trap.  To do so we must prepare a chain of two 
  4935. snmp_dpi_set_packet structures, which looks like: 
  4936.  
  4937. struct dpi_set_packet {
  4938.   char                   *object_p;   /* ptr to OIDstring     */
  4939.   char                   *group_p;    /* ptr to sub-tree      */
  4940.   char                   *instance_p; /* ptr to rest of OID   */
  4941.   unsigned char           value_type; /* SNMP_TYPE_xxxx       */
  4942.   unsigned short          value_len;  /* value length         */
  4943.   char                   *value_p;    /* ptr to value itself  */
  4944.   struct dpi_set_packet  *next_p;     /* ptr to next in chain */
  4945. };
  4946. typedef struct dpi_set_packet        snmp_dpi_set_packet;
  4947. #define snmp_dpi_set_packet_NULL_p   ((snmp_dpi_set_packet *)0)
  4948.  
  4949. We can use the mkDPIset() function to prepare such a structure. This function 
  4950. expects the following parameters: 
  4951.  
  4952.      A pointer to an existing snmp_dpi_set_packet structure if the new varBind 
  4953.       must be added to an existing chain of varBinds.  If this is the first or 
  4954.       the only varBind in the chain, pass the snmp_dpi_set_packet_NULL_p 
  4955.       pointer to indicate this. 
  4956.  
  4957.      A pointer to the sub-tree that we registered. 
  4958.  
  4959.      A pointer to the rest of the OID, in other words, the piece that follows 
  4960.       the sub-tree. 
  4961.  
  4962.      The value type of the value to be bound to the variable name.  This is 
  4963.       must be one of the SNMP_TYPE_xxxx values as defined in the snmp_dpi.h 
  4964.       include file. 
  4965.  
  4966.      The length of the value.  For integer type values, this must be a length 
  4967.       of 4.  We always work with 32-bit signed or unsigned integers except for 
  4968.       the Counter64 type.  For the Counter64 type, we must point to a 
  4969.       snmp_dpi_u64 structure and pass the length of that structure. 
  4970.  
  4971.      A pointer to the value. 
  4972.  
  4973.  Memory for the varBind is dynamically allocated and the data itself is copied. 
  4974.  Upon return, we can dispose of our own pointers and allocated memory as we 
  4975.  please.  If the call is successful, a pointer is returned as follows: 
  4976.  
  4977.      To a new snmp_dpi_set_packet if it is the first or only varBind. 
  4978.  
  4979.      To the existing snmp_dpi_set_packet that we passed on the call.  In this 
  4980.       case, the new packed has been chained to the end of the varBind list. 
  4981.  
  4982.  If the mkDPIset() call fails, a NULL pointer is returned. 
  4983.  
  4984.  Once we have prepared the SET-varBind data, we can create a DPI TRAP packet. 
  4985.  To do so we can use the mkDPItrap() function which expects these parameters: 
  4986.  
  4987.      The generic trap code.  Use 6 for enterprise specific trap type. 
  4988.  
  4989.      The specific trap type.  This is a type that is defined by the MIB which 
  4990.       we are implementing.  In our example we just use a 1. 
  4991.  
  4992.      A pointer to a chain of varBinds or the NULL pointer if no varBinds need 
  4993.       to be passed with the trap. 
  4994.  
  4995.      A pointer to the enterprise OID if we want to use a different enterprise 
  4996.       ID than the OID we used to identify ourselves as a subagent at DPI-OPEN 
  4997.       time. 
  4998.  
  4999.  The following code creates an enterprise specific trap with specific type 1 
  5000.  and passes two varBinds.  The first varBind with our object 1, instance 0, 
  5001.  Integer32 value; the second varBind with our object 2, instance 0, Octet 
  5002.  String.  We pass no enterprise ID. 
  5003.  
  5004.   static int do_trap(void)
  5005.   {
  5006.     unsigned char       *packet_p;
  5007.     int                  rc;
  5008.     snmp_dpi_set_packet *varBind_p;
  5009.  
  5010.     varBind_p =                        /* init the varBindchain */
  5011.        snmp_dpi_set_packet_NULL_p,     /* to a NULL pointer     */
  5012.  
  5013.     varBind_p = mkDPIset(              /* Make DPI set packet   */
  5014.                   varBind_p,           /* ptr to varBind chain  */
  5015.                   DPI_SIMPLE_MIB,      /* ptr to sub-tree       */
  5016.                   DPI_SIMPLE_INTEGER,  /* ptr to rest of OID    */
  5017.                   SNMP_TYPE_Integer32, /* value type Integer 32 */
  5018.                   sizeof(value1),      /* length of value       */
  5019.                   &value1);            /* ptr to value          */
  5020.  
  5021.     if (!varBind_p) return(-1);        /* If it failed, return  */
  5022.  
  5023.     varBind_p = mkDPIset(                 /* Make DPI set packet*/
  5024.                   varBind_p,              /* ptr to varBindchain*/
  5025.                   DPI_SIMPLE_MIB,         /* ptr to sub-tree    */
  5026.                   DPI_SIMPLE_STRING,      /* ptr to rest of OID */
  5027.                   SNMP_TYPE_DisplayString,/* value type         */
  5028.                   strlen(value2_p),       /* length of value    */
  5029.                   value2_p);              /* ptr to value       */
  5030.  
  5031.     if (!varBind_p) return(-1);        /* If it failed, return  */
  5032.  
  5033.  
  5034.     varBind_p = mkDPIset(                 /* Make DPI set packet*/
  5035.                   varBind_p,              /* ptr to varBindchain*/
  5036.                   DPI_SIMPLE_MIB,         /* ptr to sub-tree    */
  5037.                   DPI_SIMPLE_COUNTER32,   /* ptr to rest of OID */
  5038.                   SNMP_TYPE_Counter32,    /* value type         */
  5039.                   sizeof(value3),         /* length of value    */
  5040.                   &value3);               /* ptr to value       */
  5041.  
  5042.     if (!varBind_p) return(-1);        /* If it failed, return  */
  5043.  
  5044.     packet_p = mkDPItrap(              /* Make DPItrap packet   */
  5045.                  6,                    /* enterpriseSpecific    */
  5046.                  1,                    /* specific type = 1     */
  5047.                  varBind_p,            /* varBind data, and use */
  5048.                  (char *)0);           /* default enterpriseID  */
  5049.  
  5050.     if (!packet_p) return(-1);         /* If it failed, return  */
  5051.  
  5052.     rc  = DPIsend_packet_to_agent(     /* send TRAP packet      */
  5053.              handle,                   /* on this connection    */
  5054.              packet_p,                 /* this is the packet    */
  5055.              DPI_PACKET_LEN(packet_p));/* and this is its length*/
  5056.  
  5057.     return(rc);                        /* return retcode        */
  5058.   } /* end of do_trap() */
  5059.  
  5060.  
  5061. ΓòÉΓòÉΓòÉ 12. Notices ΓòÉΓòÉΓòÉ
  5062.  
  5063. Second Edition (September 1996) 
  5064.  
  5065. The following paragraph does not apply to the United Kingdom or any country 
  5066. where such provisions are inconsistent with local law:  INTERNATIONAL BUSINESS 
  5067. MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY 
  5068. KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
  5069. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states 
  5070. do not allow disclaimer of express or implied warranties in certain 
  5071. transactions, therefore, this statement may not apply to you. 
  5072.  
  5073. This publication could include technical inaccuracies or typographical errors. 
  5074. Changes are periodically made to the information herein; these changes will be 
  5075. incorporated in new editions of the publication. IBM may make improvements 
  5076. and/or changes in the product(s) and/or the program(s) described in this 
  5077. publication at any time. 
  5078.  
  5079. It is possible that this publication may contain reference to, or information 
  5080. about, IBM products (machines and programs), programming, or services that are 
  5081. not announced in your country.  Such references or information must not be 
  5082. construed to mean that IBM intends to announce such IBM products, programming, 
  5083. or services in your country. 
  5084.  
  5085. Requests for technical information about IBM products should be made to your 
  5086. IBM reseller or IBM marketing representative. 
  5087.  
  5088.  
  5089. ΓòÉΓòÉΓòÉ 12.1. Copyright Notices ΓòÉΓòÉΓòÉ
  5090.  
  5091. COPYRIGHT LICENSE: This publication contains printed sample application 
  5092. programs in source language, which illustrate OS/2 programming techniques. You 
  5093. may copy, modify, and distribute these sample programs in any form without 
  5094. payment to IBM, for the purposes of developing, using, marketing or 
  5095. distributing application programs conforming to the OS/2 application 
  5096. programming interface. 
  5097.  
  5098. Each copy of any portion of these sample programs or any derivative work, which 
  5099. is distributed to others, must include a copyright notice as follows: "(C) 
  5100. (your company name) (year).  All rights reserved." 
  5101.  
  5102. (C)Copyright International Business Machines Corporation 1995, 1996.  All 
  5103. rights reserved. 
  5104. Note to U.S. Government Users - Documentation related to restricted rights - 
  5105. Use, duplication or disclosure is subject to restrictions set forth in GSA ADP 
  5106. Schedule Contract with IBM Corp. 
  5107.  
  5108.  
  5109. ΓòÉΓòÉΓòÉ 12.2. Disclaimers ΓòÉΓòÉΓòÉ
  5110.  
  5111. References in this publication to IBM products, programs, or services do not 
  5112. imply that IBM intends to make these available in all countries in which IBM 
  5113. operates. Any reference to an IBM product, program or service is not intended 
  5114. to state or imply that only that IBM product, program, or service may be used. 
  5115. Subject to IBM's valid intellectual property or other legally protectable 
  5116. rights, any functionally equivalent product, program, or service may be used 
  5117. instead of the IBM product, program, or service. The evaluation and 
  5118. verification of operation in conjunction with other products, except those 
  5119. expressly designated by IBM, are the responsibility of the user. 
  5120.  
  5121. IBM may have patents or pending patent applications covering subject matter in 
  5122. this document. The furnishing of this document does not give you any license to 
  5123. these patents. You can send license inquiries, in writing, to: 
  5124.  
  5125.       IBM Director of Licensing 
  5126.       IBM Corporation 
  5127.       500 Columbus Avenue 
  5128.       Thornwood, NY  10594 
  5129.       U.S.A. 
  5130.  
  5131.  Asia-Pacific users can inquire, in writing, to the IBM Director of 
  5132.  Intellectual Property and Licensing, IBM World Trade Asia Corporation, 2-31 
  5133.  Roppongi 3-chome, Minato-ku, Tokyo 106, Japan. 
  5134.  
  5135.  Licensees of this program who wish to have information about it for the 
  5136.  purpose of enabling: (i) the exchange of information between independently 
  5137.  created programs and other programs (including this one) and (ii) the mutual 
  5138.  use of the information which has been exchanged, should contact IBM 
  5139.  Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A.  Such 
  5140.  information may be available, subject to appropriate terms and conditions, 
  5141.  including in some cases, payment of a fee. 
  5142.  
  5143.  
  5144. ΓòÉΓòÉΓòÉ 12.3. Trademarks ΓòÉΓòÉΓòÉ
  5145.  
  5146. The following terms are trademarks of the IBM Corporation in the United States 
  5147. or other countries or both: 
  5148.  
  5149. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  5150. Γöé Common User Access           Γöé DB2/2                 Γöé
  5151. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  5152. Γöé DATABASE 2               Γöé FFST/2                Γöé
  5153. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  5154. Γöé First Failure Support Technology/2   Γöé IBM                  Γöé
  5155. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  5156. Γöé Operating System/2           Γöé OS/2                 Γöé
  5157. Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  5158. Γöé SystemView               Γöé                    Γöé
  5159. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  5160.  
  5161. The following terms are trademarks of other companies: 
  5162.  
  5163.  Term              Trademark of 
  5164.  DMI               Desktop Management Task Force 
  5165.  DMTF              Desktop Management Task Force 
  5166.  Windows NT        Microsoft Corporation 
  5167.  Win32             Microsoft Corporation 
  5168.  X-Windows         Massachusetts Institute of Technology 
  5169.  
  5170.  Microsoft, Windows and the Windows 95 Logo are trademarks of Microsoft 
  5171.  Corporation. 
  5172.  
  5173.  Other company, product, and service names, which may be denoted by a double 
  5174.  asterisk (**), may be trademarks or service marks of others. 
  5175.  
  5176.  
  5177. ΓòÉΓòÉΓòÉ 13. Glossary ΓòÉΓòÉΓòÉ
  5178.  
  5179. This glossary includes terms and definitions from: 
  5180.  
  5181.      The American National Standard Dictionary for Information Systems, ANSI 
  5182.       X3.172-1990, copyright 1990 by the American National Standards Institute 
  5183.       (ANSI). Copies may be purchased from the American National Standards 
  5184.       Institute, 11 West 42nd Street, New York, New York  10036. Definitions 
  5185.       are identified by the symbol (A) after the definition. 
  5186.  
  5187.      The ANSI/EIA Standard-440-A, Fiber Optic Terminology. Copies may be 
  5188.       purchased from the Electronic Industries Association, 2001 Pennsylvania 
  5189.       Avenue, N.W., Washington, DC 20006. Definitions are identified by the 
  5190.       symbol (E) after the definition. 
  5191.  
  5192.      The Information Technology Vocabulary, developed by Subcommittee 1, Joint 
  5193.       Technical Committee 1, of the International Organization for 
  5194.       Standardization and the International Electrotechnical Commission 
  5195.       (ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are 
  5196.       identified by the symbol (I) after the definition; definitions taken from 
  5197.       draft international standards, committee drafts, and working papers being 
  5198.       developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the 
  5199.       definition, indicating that final agreement has not yet been reached 
  5200.       among the participating National Bodies of SC1. 
  5201.  
  5202.      The IBM Dictionary of Computing, New York: McGraw-Hill, 1994. 
  5203.  
  5204.      Internet Request for Comments: 1208, Glossary of Networking Terms. 
  5205.  
  5206.      Internet Request for Comments: 1392, Internet Users' Glossary. 
  5207.  
  5208.      The Object-Oriented Interface Design: IBM Common User Access Guidelines, 
  5209.       Carmel, Indiana: Que, 1992. 
  5210.  
  5211.      The Desktop Management Interface Reference, Revision 1.0 
  5212.  
  5213.      The Desktop Management Interface Specification, Version 2.0 
  5214.  
  5215.  The following cross-references are used in this glossary: 
  5216.  
  5217.  Contrast with: This refers to a term that has an opposed or substantively 
  5218.            different meaning. 
  5219.  
  5220.  Synonym for: This indicates that the term has the same meaning as a preferred 
  5221.            term, which is defined in its proper place in the glossary. 
  5222.  
  5223.  Synonymous with: This is a backward reference from a defined term to all other 
  5224.            terms that have the same meaning. 
  5225.  
  5226.  See:      This refers the reader to multiple-word terms that have the same 
  5227.            last word. 
  5228.  
  5229.  See also: This refers the reader to terms that have a related, but not 
  5230.            synonymous, meaning. 
  5231.  
  5232.  Deprecated term for: This indicates that the term should not be used. It 
  5233.            refers to a preferred term, which is defined in its proper place in 
  5234.            the glossary. 
  5235.  
  5236.  
  5237. ΓòÉΓòÉΓòÉ 13.1. A ΓòÉΓòÉΓòÉ
  5238.  
  5239.  
  5240. ΓòÉΓòÉΓòÉ 13.1.1. agent ΓòÉΓòÉΓòÉ
  5241.  
  5242. agent 
  5243.  
  5244.    1. In systems management, a user that, for a particular interaction, has 
  5245.       assumed an agent role. 
  5246.  
  5247.    2. An entity that represents one or more managed objects by (a) emitting 
  5248.       notifications regarding the objects and (b) handling requests from 
  5249.       managers for management operations to modify or query the objects. 
  5250.  
  5251.    3. A system that assumes an agent role. 
  5252.  
  5253.  
  5254. ΓòÉΓòÉΓòÉ 13.1.2. attribute ΓòÉΓòÉΓòÉ
  5255.  
  5256. attribute 
  5257.  
  5258.    1. A characteristic that identifies and describes a managed object. The 
  5259.       characteristic can be determined, and possibly changed, through 
  5260.       operations on the managed object. 
  5261.  
  5262.    2. Information within a managed object that is visible at the object 
  5263.       boundary. An attribute has a type, which indicates the range of 
  5264.       information given by the attribute, and a value, which is within that 
  5265.       range. 
  5266.  
  5267.    3. Variable data that is logically a part of an object and that represents a 
  5268.       property of the object. For example, a serial number is an attribute of 
  5269.       an equipment object. 
  5270.  
  5271.    4. In the Desktop Management Interface (DMI), a piece of information about a 
  5272.       component. 
  5273.  
  5274.  
  5275. ΓòÉΓòÉΓòÉ 13.2. C ΓòÉΓòÉΓòÉ
  5276.  
  5277.  
  5278. ΓòÉΓòÉΓòÉ 13.2.1. component ΓòÉΓòÉΓòÉ
  5279.  
  5280. component 
  5281.  
  5282.    1. Hardware or software that is part of a functional unit. 
  5283.  
  5284.    2. A part of a structured type or value, such as an array element or a 
  5285.       record field. 
  5286.  
  5287.    3. In the Desktop Management Interface (DMI), any hardware, software, or 
  5288.       firmware element contained in (or primarily attached to) a computer 
  5289.       system. 
  5290.  
  5291.  
  5292. ΓòÉΓòÉΓòÉ 13.2.2. component instrumentation ΓòÉΓòÉΓòÉ
  5293.  
  5294. component instrumentation 
  5295.  
  5296. In the Desktop Management Interface (DMI), the executable code that provides 
  5297. DMI management functionality for a particular component. 
  5298.  
  5299.  
  5300. ΓòÉΓòÉΓòÉ 13.2.3. CONFIG.SYS file ΓòÉΓòÉΓòÉ
  5301.  
  5302. CONFIG.SYS file 
  5303.  
  5304. A file that contains configuration options for an OS/2 program installed on a 
  5305. workstation. 
  5306.  
  5307.  
  5308. ΓòÉΓòÉΓòÉ 13.3. D ΓòÉΓòÉΓòÉ
  5309.  
  5310.  
  5311. ΓòÉΓòÉΓòÉ 13.3.1. Desktop Management Interface (DMI) ΓòÉΓòÉΓòÉ
  5312.  
  5313. Desktop Management Interface (DMI) 
  5314.  
  5315. A protocol-independent set of application programming interfaces (APIs) defined 
  5316. by the Desktop Management Task Force (DMTF). These interfaces give management 
  5317. applications standardized access to information about hardware and software in 
  5318. a system. 
  5319.  
  5320.  
  5321. ΓòÉΓòÉΓòÉ 13.3.2. Desktop Management Task Force (DMTF) ΓòÉΓòÉΓòÉ
  5322.  
  5323. Desktop Management Task Force (DMTF) 
  5324.  
  5325. An alliance of computer vendors which was convened to streamline the management 
  5326. of diverse operating systems commonly found in an enterprise.  The DMTF 
  5327. includes industry-wide workgroups, which are actively identifying the pieces of 
  5328. information which are necessary to manage specific categories of devices. 
  5329.  
  5330.  
  5331. ΓòÉΓòÉΓòÉ 13.3.3. DMI ΓòÉΓòÉΓòÉ
  5332.  
  5333. DMI 
  5334.  
  5335. Desktop Management Interface. 
  5336.  
  5337.  
  5338. ΓòÉΓòÉΓòÉ 13.3.4. DMTF ΓòÉΓòÉΓòÉ
  5339.  
  5340. DMTF 
  5341.  
  5342. Desktop Management Task Force. 
  5343.  
  5344.  
  5345. ΓòÉΓòÉΓòÉ 13.3.5. DPI ΓòÉΓòÉΓòÉ
  5346.  
  5347. DPI 
  5348.  
  5349. Distributed Protocol Interface. 
  5350.  
  5351.  
  5352. ΓòÉΓòÉΓòÉ 13.3.6. discovery ΓòÉΓòÉΓòÉ
  5353.  
  5354. discovery 
  5355.  
  5356. The automatic detection of network topology change, for example, new and 
  5357. deleted nodes or interfaces. 
  5358.  
  5359.  
  5360. ΓòÉΓòÉΓòÉ 13.3.7. Distributed Protocol Interface (DPI) ΓòÉΓòÉΓòÉ
  5361.  
  5362. Distributed Protocol Interface (DPI) 
  5363.  
  5364. An interface between a Simple Network Management Protocol (SNMP) agent and its 
  5365. subagents that is defined in Request for Comments (RFC) 1592. 
  5366.  
  5367.  
  5368. ΓòÉΓòÉΓòÉ 13.3.8. drive ΓòÉΓòÉΓòÉ
  5369.  
  5370. drive 
  5371.  
  5372. The device used to read and write data on disks or diskettes. 
  5373.  
  5374.  
  5375. ΓòÉΓòÉΓòÉ 13.4. E ΓòÉΓòÉΓòÉ
  5376.  
  5377.  
  5378. ΓòÉΓòÉΓòÉ 13.4.1. event ΓòÉΓòÉΓòÉ
  5379.  
  5380. event 
  5381.  
  5382.    1. An occurrence of significance to a task; for example, an SNMP trap, the 
  5383.       opening of a window or a submap, or the completion of an asynchronous 
  5384.       operation. 
  5385.  
  5386.    2. In the NetView and NETCENTER programs, a record indicating irregularities 
  5387.       of operation in physical elements of a network. 
  5388.  
  5389.    3. In the Desktop Management Interface (DMI), a type of indication 
  5390.       (unsolicited report) that originates from a component instrumentation. 
  5391.       See also indication. 
  5392.  
  5393.  
  5394. ΓòÉΓòÉΓòÉ 13.5. G ΓòÉΓòÉΓòÉ
  5395.  
  5396.  
  5397. ΓòÉΓòÉΓòÉ 13.5.1. group ΓòÉΓòÉΓòÉ
  5398.  
  5399. group 
  5400.  
  5401.    1. In the NetView/PC program, to identify a set of application programs that 
  5402.       are to run concurrently. 
  5403.  
  5404.    2. In the Desktop Management Interface (DMI), a collection of attributes.  A 
  5405.       group with multiple instances is called a table. 
  5406.  
  5407.  
  5408. ΓòÉΓòÉΓòÉ 13.6. H ΓòÉΓòÉΓòÉ
  5409.  
  5410.  
  5411. ΓòÉΓòÉΓòÉ 13.6.1. host name ΓòÉΓòÉΓòÉ
  5412.  
  5413. host name 
  5414.  
  5415. A unique name, set at the management protocol level, that identifies a node. 
  5416.  
  5417.  
  5418. ΓòÉΓòÉΓòÉ 13.7. I ΓòÉΓòÉΓòÉ
  5419.  
  5420.  
  5421. ΓòÉΓòÉΓòÉ 13.7.1. ID ΓòÉΓòÉΓòÉ
  5422.  
  5423. ID 
  5424.  
  5425. Identification; identifier. 
  5426.  
  5427.  
  5428. ΓòÉΓòÉΓòÉ 13.7.2. indication ΓòÉΓòÉΓòÉ
  5429.  
  5430. indication 
  5431.  
  5432. In the Desktop Management Interface (DMI), an unsolicited report, either from a 
  5433. component instrumentation to the service provider, or from the service provider 
  5434. to a management application. 
  5435.  
  5436.  
  5437. ΓòÉΓòÉΓòÉ 13.7.3. instrumentation ΓòÉΓòÉΓòÉ
  5438.  
  5439. instrumentation 
  5440.  
  5441. See component instrumentation. 
  5442.  
  5443.  
  5444. ΓòÉΓòÉΓòÉ 13.8. K ΓòÉΓòÉΓòÉ
  5445.  
  5446.  
  5447. ΓòÉΓòÉΓòÉ 13.8.1. key ΓòÉΓòÉΓòÉ
  5448.  
  5449. key 
  5450.  
  5451. In the Desktop Management Interface (DMI), an identifier of a particular 
  5452. instance (row) of a table. 
  5453.  
  5454.  
  5455. ΓòÉΓòÉΓòÉ 13.9. L ΓòÉΓòÉΓòÉ
  5456.  
  5457.  
  5458. ΓòÉΓòÉΓòÉ 13.9.1. load ΓòÉΓòÉΓòÉ
  5459.  
  5460. load 
  5461.  
  5462. To move data or programs into memory. 
  5463.  
  5464.  
  5465. ΓòÉΓòÉΓòÉ 13.10. M ΓòÉΓòÉΓòÉ
  5466.  
  5467.  
  5468. ΓòÉΓòÉΓòÉ 13.10.1. management application ΓòÉΓòÉΓòÉ
  5469.  
  5470. management application 
  5471.  
  5472. In the Desktop Management Interface (DMI), code that uses the management 
  5473. interface (MI) to request management activity from components. 
  5474.  
  5475.  
  5476. ΓòÉΓòÉΓòÉ 13.10.2. Management Information Base (MIB) ΓòÉΓòÉΓòÉ
  5477.  
  5478. Management Information Base (MIB) 
  5479.  
  5480.    1. A collection of objects that can be accessed by means of a network 
  5481.       management protocol. 
  5482.  
  5483.    2. A definition for management information that specifies the information 
  5484.       available from a host or gateway and the operations allowed. 
  5485.  
  5486.    3. In OSI, the conceptual repository of management information within an 
  5487.       open system. 
  5488.  
  5489.  
  5490. ΓòÉΓòÉΓòÉ 13.10.3. Management Information Format (MIF) ΓòÉΓòÉΓòÉ
  5491.  
  5492. Management Information Format (MIF) 
  5493.  
  5494. In the Desktop Management Interface (DMI), the format used for describing 
  5495. components. 
  5496.  
  5497.  
  5498. ΓòÉΓòÉΓòÉ 13.10.4. Management Interface (MI) ΓòÉΓòÉΓòÉ
  5499.  
  5500. Management Interface (MI) 
  5501.  
  5502. In the Desktop Management Interface (DMI), the DMI layer between management 
  5503. applications and the service provider. 
  5504.  
  5505.  
  5506. ΓòÉΓòÉΓòÉ 13.10.5. MI ΓòÉΓòÉΓòÉ
  5507.  
  5508. MI 
  5509.  
  5510. Management interface. 
  5511.  
  5512.  
  5513. ΓòÉΓòÉΓòÉ 13.10.6. MIB ΓòÉΓòÉΓòÉ
  5514.  
  5515. MIB 
  5516.  
  5517. Management Information Base. 
  5518.  
  5519.  
  5520. ΓòÉΓòÉΓòÉ 13.10.7. MIF ΓòÉΓòÉΓòÉ
  5521.  
  5522. MIF 
  5523.  
  5524. Management Information Format. 
  5525.  
  5526.  
  5527. ΓòÉΓòÉΓòÉ 13.10.8. MIF database ΓòÉΓòÉΓòÉ
  5528.  
  5529. MIF database 
  5530.  
  5531. In the Desktop Management Interface (DMI), the collection of known MIF files, 
  5532. stored by the service provider (in an implementation-specific format) for fast 
  5533. access. 
  5534.  
  5535.  
  5536. ΓòÉΓòÉΓòÉ 13.10.9. MIF file ΓòÉΓòÉΓòÉ
  5537.  
  5538. MIF file 
  5539.  
  5540. In the Desktop Management Interface (DMI), a file that uses the MIF to describe 
  5541. a component. 
  5542.  
  5543.  
  5544. ΓòÉΓòÉΓòÉ 13.11. O ΓòÉΓòÉΓòÉ
  5545.  
  5546.  
  5547. ΓòÉΓòÉΓòÉ 13.11.1. object identifier (OID) ΓòÉΓòÉΓòÉ
  5548.  
  5549. object identifier (OID) 
  5550.  
  5551. An administratively assigned data value of the type defined in abstract syntax 
  5552. notation 1 (ASN.1). 
  5553.  
  5554.  
  5555. ΓòÉΓòÉΓòÉ 13.11.2. OID ΓòÉΓòÉΓòÉ
  5556.  
  5557. OID 
  5558.  
  5559. Object ID. 
  5560.  
  5561.  
  5562. ΓòÉΓòÉΓòÉ 13.12. P ΓòÉΓòÉΓòÉ
  5563.  
  5564.  
  5565. ΓòÉΓòÉΓòÉ 13.12.1. process ΓòÉΓòÉΓòÉ
  5566.  
  5567. process 
  5568.  
  5569.    1. A unique, finite course of events defined by its purpose or by its 
  5570.       effect, achieved under defined conditions. 
  5571.  
  5572.    2. Any operation or combination of operations on data. 
  5573.  
  5574.    3. A function being performed or waiting to be performed. 
  5575.  
  5576.    4. A program in operation; for example, a daemon is a system process that is 
  5577.       always running on the system. 
  5578.  
  5579.    5. An address space, one or more threads of control that run within that 
  5580.       address space, and the required system resources. 
  5581.  
  5582.    6. A collection of system resources that include one or more threads of 
  5583.       execution that perform a task. 
  5584.  
  5585.  
  5586. ΓòÉΓòÉΓòÉ 13.12.2. protocol ΓòÉΓòÉΓòÉ
  5587.  
  5588. protocol 
  5589.  
  5590.    1. A set of semantic and syntactic rules that determines the behavior of 
  5591.       functional units in achieving communication. (I) Protocols can determine 
  5592.       low-level details of machine-to-machine interfaces, such as the order in 
  5593.       which bits from a byte are sent; they can also determine high-level 
  5594.       exchanges between application programs, such as file transfer. 
  5595.  
  5596.    2. A set of rules governing the operation of functional units of a 
  5597.       communication system that must be followed if communication is to take 
  5598.       place. 
  5599.  
  5600.    3. In Open Systems Interconnection architecture, a set of semantic and 
  5601.       syntactic rules that determine the behavior of entities in the same layer 
  5602.       in performing communication functions. (T) 
  5603.  
  5604.  
  5605. ΓòÉΓòÉΓòÉ 13.13. R ΓòÉΓòÉΓòÉ
  5606.  
  5607.  
  5608. ΓòÉΓòÉΓòÉ 13.13.1. Request for Comments (RFC) ΓòÉΓòÉΓòÉ
  5609.  
  5610. Request for Comments (RFC) 
  5611.  
  5612. In Internet communications, the document series that describes a part of the 
  5613. Internet suite of protocols and related experiments. All Internet standards are 
  5614. documented as RFCs. 
  5615.  
  5616.  
  5617. ΓòÉΓòÉΓòÉ 13.13.2. RFC ΓòÉΓòÉΓòÉ
  5618.  
  5619. RFC 
  5620.  
  5621. Request for Comments. 
  5622.  
  5623.  
  5624. ΓòÉΓòÉΓòÉ 13.14. S ΓòÉΓòÉΓòÉ
  5625.  
  5626.  
  5627. ΓòÉΓòÉΓòÉ 13.14.1. service provider ΓòÉΓòÉΓòÉ
  5628.  
  5629. service provider 
  5630.  
  5631. In the Desktop Management Interface (DMI), the code between the management 
  5632. interface and the component interface that arbitrates access to component 
  5633. instrumentation and manages the MIF database. 
  5634.  
  5635.  
  5636. ΓòÉΓòÉΓòÉ 13.14.2. Simple Network Management Protocol (SNMP) ΓòÉΓòÉΓòÉ
  5637.  
  5638. Simple Network Management Protocol (SNMP) 
  5639.  
  5640. In the Internet suite of protocols, a network management protocol that is used 
  5641. to monitor routers and attached networks. SNMP is an application layer 
  5642. protocol. Information on devices managed is defined and stored in the 
  5643. application's Management Information Base (MIB). 
  5644.  
  5645.  
  5646. ΓòÉΓòÉΓòÉ 13.14.3. SNMP ΓòÉΓòÉΓòÉ
  5647.  
  5648. SNMP 
  5649.  
  5650. Simple Network Management Protocol. 
  5651.  
  5652.  
  5653. ΓòÉΓòÉΓòÉ 13.14.4. system ΓòÉΓòÉΓòÉ
  5654.  
  5655. system 
  5656.  
  5657.    1. A computer and its associated devices and programs. 
  5658.  
  5659.    2. An end point of a communications link or a junction common to two or more 
  5660.       links in a network.  Systems can be processors, communication 
  5661.       controllers, cluster controllers, terminals, workstations, clients, 
  5662.       requesters, or servers. 
  5663.  
  5664.  
  5665. ΓòÉΓòÉΓòÉ 13.15. T ΓòÉΓòÉΓòÉ
  5666.  
  5667.  
  5668. ΓòÉΓòÉΓòÉ 13.15.1. table ΓòÉΓòÉΓòÉ
  5669.  
  5670. table 
  5671.  
  5672. In the Desktop Management Interface (DMI), a multidimensional group; a group 
  5673. with more than one instance. 
  5674.  
  5675.  
  5676. ΓòÉΓòÉΓòÉ 13.15.2. TCP/IP ΓòÉΓòÉΓòÉ
  5677.  
  5678. TCP/IP 
  5679.  
  5680. Transmission Control Protocol/Internet Protocol. 
  5681.  
  5682.  
  5683. ΓòÉΓòÉΓòÉ 13.15.3. topology ΓòÉΓòÉΓòÉ
  5684.  
  5685. topology 
  5686.  
  5687. The schematic arrangement of the links and nodes of a network. 
  5688.  
  5689.  
  5690. ΓòÉΓòÉΓòÉ 13.15.4. Transmission Control Protocol/Internet Protocol (TCP/IP) ΓòÉΓòÉΓòÉ
  5691.  
  5692. Transmission Control Protocol/Internet Protocol (TCP/IP) 
  5693.  
  5694. A set of communication protocols that supports peer-to-peer connectivity 
  5695. functions for both local and wide-area networks. 
  5696.  
  5697.  
  5698. ΓòÉΓòÉΓòÉ 13.15.5. trap ΓòÉΓòÉΓòÉ
  5699.  
  5700. trap 
  5701.  
  5702. In the Simple Network Management Protocol (SNMP), a message sent by a managed 
  5703. node (agent function) to a management station to report an exception condition. 
  5704.  
  5705.  
  5706. ΓòÉΓòÉΓòÉ 13.16. U ΓòÉΓòÉΓòÉ
  5707.  
  5708.  
  5709. ΓòÉΓòÉΓòÉ 13.16.1. UDP ΓòÉΓòÉΓòÉ
  5710.  
  5711. UDP 
  5712.  
  5713. User Datagram Protocol. 
  5714.  
  5715.  
  5716. ΓòÉΓòÉΓòÉ 13.16.2. User Datagram Protocol (UDP) ΓòÉΓòÉΓòÉ
  5717.  
  5718. User Datagram Protocol (UDP) 
  5719.  
  5720. In the Internet suite of protocols, a protocol that provides unreliable, 
  5721. connectionless datagram service. It enables an application program on one 
  5722. machine or process to send a datagram to an application program on another 
  5723. machine or process. UDP uses the Internet Protocol (IP) to deliver datagrams. 
  5724.  
  5725.  
  5726. ΓòÉΓòÉΓòÉ 14. Bibliography ΓòÉΓòÉΓòÉ
  5727.  
  5728. This bibliography contains a list of publications pertaining to the product and 
  5729. related subjects. 
  5730.  
  5731.  
  5732. ΓòÉΓòÉΓòÉ 14.1. SystemView Agent Publications ΓòÉΓòÉΓòÉ
  5733.  
  5734. The following paragraphs briefly describe the library for Version 1 of the 
  5735. SystemView Agent program: 
  5736.  
  5737. SystemView Agent User's Guide (SVAG-USR2) 
  5738.  
  5739. This book provides instructions for installing the SystemView Agent package and 
  5740. using the MIF browser and describes communication with SNMP management 
  5741. applications. 
  5742.  
  5743. SystemView Agent DMI Programmer's Guide (SVAG-DMIP) 
  5744.  
  5745. This books describes the operation of the DMI, including the command blocks and 
  5746. the conventions of the MIF. The book also discusses how to enable components 
  5747. for DMI access and how DMI information is made available to SNMP management 
  5748. applications. 
  5749.  
  5750. SystemView Agent DPI Programmer's Guide (SVAG-DPIP) 
  5751.  
  5752. This book describes the distributed protocol interface (DPI), including 
  5753. programming concepts, basic API functions, and examples. 
  5754.  
  5755.  
  5756. ΓòÉΓòÉΓòÉ 14.2. Desktop Management Task Force Publications ΓòÉΓòÉΓòÉ
  5757.  
  5758. The following publications are available from the Desktop Management Task 
  5759. Force: 
  5760.  
  5761. Desktop Management Interface Specification, Version 1.1 
  5762.  
  5763.  
  5764. ΓòÉΓòÉΓòÉ 14.3. Internet Request for Comments Documents ΓòÉΓòÉΓòÉ
  5765.  
  5766. The Internet protocol suite is still evolving through Requests for Comments 
  5767. (RFCs).  New protocols are being designed and implemented by researchers and 
  5768. are brought to the attention of the Internet community in the form of RFCs. 
  5769.  
  5770. As networks have grown in size and complexity, SNMP has emerged as the Internet 
  5771. network management standard. The following RFCs provide information relevant to 
  5772. SNMP and related to SystemView Agent: 
  5773.  
  5774. RFC 1155: Structure and Identification of Management Information for 
  5775. TCP/IP-based Internets 
  5776.  
  5777. This RFC provides a set of rules used to define and identify MIB objects. 
  5778.  
  5779. RFC 1157:  A Simple Network Management Protocol (SNMP) 
  5780.  
  5781. This RFC defines the protocol used to manage objects defined in a MIB. 
  5782.  
  5783. RFC 1212:  Concise MIB Definitions 
  5784.  
  5785. RFC 1213:  Management Information Base for Network Management of TCP/IP-based 
  5786. Internets:  MIB-II 
  5787.  
  5788. This RFC defines a base set of managed objects to be provided in a MIB. 
  5789.  
  5790. RFC 1592, SNMP Distributed Protocol Interface (DPI), Version 2.0 
  5791.  
  5792. This RFC describes the protocol to allow an SNMP agent to communicate with a 
  5793. subagent. This allows users to dynamically add, delete, or replace MIB objects 
  5794. without recompiling the SNMP agent. 
  5795.  
  5796. RFC 1901, Introduction to Community-based SNMPv2 
  5797.  
  5798. RFC 1902, Structure of Management Information for Version 2 of the Simple 
  5799. Network Management Protocol (SNMPv2) 
  5800.  
  5801. RFC 1903, Textual  Conventions for Version 2 of the Simple Network Management 
  5802. Protocol (SNMPv2) 
  5803.  
  5804. RFC 1904, Conformance  Statements for Version 2 of the Simple Network 
  5805. Management Protocol (SNMPv2) 
  5806.  
  5807. RFC 1905, Protocol Operations for Version 2 of the Simple Network Management 
  5808. Protocol (SNMPv2) 
  5809.  
  5810. RFC 1906, Transport Mappings for Version 2 of the Simple Network Management 
  5811. Protocol (SNMPv2) 
  5812.  
  5813. RFC 1907, Management Information Base for Version 2 of the Simple Network 
  5814. Management Protocol (SNMPv2) 
  5815.  
  5816. RFC 1908, Coexistence between Version 1 and Version 2 of the Internet-standard 
  5817. Network Management Framework 
  5818.  
  5819. RFC 1909, An Administrative Infrastructure for SNMPv2 
  5820.  
  5821. RFC 1910, User-based Security Model for SNMPv2