--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/oi-extras/net-snmp/sun/sdk/demo/demo_module_3/README_demo_module_3 Wed Jun 22 00:51:55 2011 +0100
@@ -0,0 +1,261 @@
+/*
+ * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
+ *
+ * U.S. Government Rights - Commercial software. Government users are subject
+ * to the Sun Microsystems, Inc. standard license agreement and applicable
+ * provisions of the FAR and its supplements.
+ *
+ *
+ * This distribution may include materials developed by third parties. Sun,
+ * Sun Microsystems, the Sun logo and Solaris are trademarks or registered
+ * trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
+ */
+
+
+README for demo_module_3
+********************************************************************
+
+This code example shows you how to modify the code generated by
+"mib2c -c mib2c.iterate.conf" command to perform data retrieval for
+a general table.
+
+
+Introduction
+------------
+
+General tables are different from simple tables in one of the following
+ways:
+ - index is not a single integer
+ - maximum index is not easily determinable
+ - not all indexes are valid
+ - table data is not directly accessible, such as the interfaces table
+
+See the System Management Agent Developer's Guide
+for more information about general tables data retrieval.
+
+
+This example uses some dummy data to perform data retrieval for a
+two-index table. It was generated by using "mib2c -c mib2c.iterate.conf"
+against the me1ContactInfoTable group in the SDK-DEMO1-MIB.
+Some functions have been added to the generated code to implement a
+link list to provide the test data.
+
+mib2c created templates called me1ContactInfoTable.c and me1ContactInfoTable.h.
+
+These were renamed demo_module_3.c and demo_module_3.h for this demo.
+Within me1ContactInfoTable.c, mib2c generated init_me1ContactInfoTable, and
+this was renamed to init_demo_module_3.
+
+Note that even though the SDK-DEMO1-MIB file contains the specification of
+tables and scalar, running mib2c with mib2c.iterate.conf
+generates template code only for the general table in the MIB.
+
+
+
+How to Use the demo_module_3 Code Example
+==========================================
+
+The demo_module_3 code example includes the following files, by default
+located in the directory /usr/demo/sma_snmp/demo_module_3.
+
+Files:
+
+o Makefile - Compiles the module source code
+o demo_module_3.c - Source code for the module
+o demo_module_3.h - Header file for the module
+o SDK-DEMO1-MIB.txt - MIB file used in the module
+
+
+To set up your environment for the demo:
+
+1. Copy the demo code to a directory for which you have write permission.
+ For example:
+
+ % cp -R /usr/demo/sma_snmp/demo_module_3 /home/username/demo
+
+
+2. Create a lib directory that you can use to store shared object libraries
+ that you generate from demo code examples, if you have not already done so.
+ For example:
+
+ % mkdir /home/username/demo/lib
+
+
+3. Create a mibs directory that you can use to store MIB files for the demo
+ code examples, if you have not already done so.
+ For example:
+
+ % mkdir /home/username/demo/mibs
+
+
+4. Set the CC environment variable to the location of the C compiler to
+ be used.
+ For example, if you are using Sun ONE Studio:
+
+ % setenv CC /opt/SUNWspro/bin/cc
+
+
+5. Set your PATH environment variable to include the appropriate paths, so that
+ needed binaries can be found during the compilation process.
+ For example, in the csh:
+
+ % setenv PATH .:/usr/bin:$PATH
+
+
+
+
+To generate code templates from the sample MIB:
+
+
+1. Change to the directory where you copied the demo module files.
+ For example:
+
+ % cd /home/username/demo/demo_module_3
+
+
+2. Copy the SDK-DEMO1-MIB.txt file to the mibs directory you created for the
+ demos, if you have not already done so.
+ For example:
+
+ % cp SDK-DEMO1-MIB.txt /home/username/demo/mibs
+
+
+3. Set your MIBS and MIBDIRS environment variables to
+ include the appropriate paths.
+ For example, in the csh:
+
+ % setenv MIBDIRS .:/home/username/demo/mibs:/etc/sma/snmp/mibs
+ % setenv MIBS +SDK-DEMO1-MIB
+
+
+4. Run mib2c on the me1ContactInfoTable group in the SDK-DEMO1-MIB.
+ For example:
+
+ % mib2c -c mib2c.iterate.conf me1ContactInfoTable
+
+ The mib2c utility generates the following template files:
+ me1ContactInfoTable.c
+ me1ContactInfoTable.h
+
+
+5. Compare the template files with the demo_module_3.c and the
+ demo_module_3.h files.
+
+ The demo_module_3 files were created by modifying the templates.
+
+ The following code is to set up the table with two indexes:
+ netsnmp_table_helper_add_indexes(table_info,
+ ASN_INTEGER, /* index: me1FloorNumber */
+ ASN_INTEGER, /* index: me1RoomNumber */
+ 0);
+
+ Care must be taken in returning the "NEXT" data when function
+ me1ContactInfoTable_get_next_data_point() is called.
+
+ For instance, in the example code:
+ me1ContactEntry* nextNode = (me1ContactEntry*) *my_loop_context;
+ nextNode = nextNode->pNext;
+
+ The table data is pre-sorted so the next data is conveniently pointed by
+ the pNext pointer. If your implementation is more complicated you should
+ make sure the OIDs increase with the immediate next OID. (xxx.1.1, xxx.1.2,
+ etc).
+
+
+
+To build the example:
+
+1. Change to the directory where you copied the demo module files.
+ For example:
+
+ % cd /home/username/demo/demo_module_3
+
+
+2. Use the make command to generate object files.
+
+ If you are running the 64-bit SPARC Solaris kernel, type:
+ % /usr/ccs/bin/make
+
+ If you are running the 32-bit SPARC Solaris kernel, type:
+ % /usr/ccs/bin/make ARCH=32
+
+ If you are running the Solaris x86 kernel, type:
+ % /usr/ccs/bin/make ARCH=32
+
+
+3. Copy the module shared library object to the lib directory you created.
+ For example:
+
+ % cp demo_module_3.so /home/username/demo/lib
+
+
+
+Setting Up Agent to Run demo_module_3
+=====================================
+
+1. As root, edit the agent's configuration file /etc/sma/snmp/snmpd.conf,
+ and insert a dlmod statement for the module. This statement enables
+ the agent to load the module.
+ For example:
+
+ dlmod demo_module_3 /home/username/demo/lib/demo_module_3.so
+
+
+2. As root, start the SMA snmp agent. If the agent is already running,
+ stop and restart it in debug mode.
+ For example:
+
+ # /etc/init.d/init.sma stop
+ # /usr/sbin/snmpd -Ddemo_module_3
+
+ The optional -Ddemo_module_3 argument sends debugging statements from
+ demo_module_3 to the /var/log/snmpd.log file. You can also use
+ the -L and -f options to send debugging statements to the screen instead.
+
+
+
+Testing the Module
+==================
+
+1. As a non-root user, issue snmptable commands to retrieve table data from
+ the module.
+ For example:
+
+
+ % snmptable -v1 -c public localhost SDK-DEMO1-MIB::me1ContactInfoTable
+
+ SNMP table: SDK-DEMO1-MIB::me1ContactInfoTable
+
+ me1FloorNumber me1RoomNumber me1Name me1Extension
+ 1 1004 John Doe 8004
+ 1 1007 John Doe 8007
+ 1 1010 John Doe 8000
+ 2 2003 John Doe 8003
+ 2 2006 John Doe 8006
+ 2 2009 John Doe 8009
+ 2 2012 John Doe 8002
+ 3 3005 John Doe 8005
+ 3 3008 John Doe 8008
+ 3 3011 John Doe 8001
+
+ or
+
+ % snmptable -v1 -c public localhost .1.3.6.1.4.1.42.2.2.4.4.1.3.1
+
+
+
+ SNMP table: SDK-DEMO1-MIB::me1ContactInfoTable
+
+ me1Extension me1Name me1RoomNumber me1FloorNumber
+ 8004 John Doe 1004 1
+ 8007 John Doe 1007 1
+ 8000 John Doe 1010 1
+ 8003 John Doe 2003 2
+ 8006 John Doe 2006 2
+ 8009 John Doe 2009 2
+ 8002 John Doe 2012 2
+ 8005 John Doe 3005 3
+ 8008 John Doe 3008 3
+ 8001 John Doe 3011 3
+
+