/*
 * 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_1
********************************************************************

This code example shows you how to modify the code generated by 
"mib2c -c mib2c.scalar.conf" command to perform a scalar
data retrieval.  See the System Management Agent Developer's Guide 
for more information about scalar data retrieval.


Introduction
------------
This example shows you how to generate templates with mib2c from a sample 
MIB.  You can then compare these templates with the source code and header
files provided with the example. The source files were created by modifying
the templates that you create in this example. 

The example also shows you how to build a module from the modified source files. 

The demo_module_1 code example includes the following files, by default 
located in the directory /usr/demo/sma_snmp/demo_module_1.

Files:

o Makefile - Compiles the module source code
o demo_module_1.c - Source code for the module, returns load averages
o demo_module_1.h - Header file for the module
o SDK-DEMO1-MIB.txt - MIB file used in the module




How to Use the demo_module_1 Code Example
==========================================


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_1  /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_1
   

2. Copy the SDK-DEMO1-MIB.txt file to the mibs directory you created 
   for the demos.
   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 me1LoadGroup group in the SDK-DEMO1-MIB.
   For example:
   
   % mib2c -c mib2c.scalar.conf me1LoadGroup

   The mib2c utility generates the following template files:
   me1LoadGroup.c 
   me1LoadGroup.h
   

5. Compare the template files with the demo_module_1.c and the
   demo_module_1.h files. 
   
   The demo_module_1 files were created by modifying the templates. 
    
   See the System Management Agent Developer's Guide for more information
   about modifying templates.   
 
   
  

To build the example:

1. Change to the directory where you copied the demo module files. 
   For example:

   % cd /home/username/demo/demo_module_1
   

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_1.so /home/username/demo/lib

   

   
   
   
Setting Up Agent to Run demo_module_1
=============================================
    
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_1 /home/username/demo/lib/demo_module_1.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_1
    
    The optional -Ddemo_module_1 argument sends debugging statements 
    from demo_module_1 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 snmpget commands to retrieve scalar data from the module.
   For example:
    
   % snmpget -v1 -c public localhost SDK-DEMO1-MIB::me1SystemLoadAvg1min.0
   % snmpget -v1 -c public localhost SDK-DEMO1-MIB::me1SystemLoadAvg5min.0 
   % snmpget -v1 -c public localhost SDK-DEMO1-MIB::me1SystemLoadAvg15min.0   
   
   Or
   
   % snmpget -v1 -c public localhost .1.3.6.1.4.1.42.2.2.4.4.1.1.1.0
   % snmpget -v1 -c public localhost .1.3.6.1.4.1.42.2.2.4.4.1.1.2.0
   % snmpget -v1 -c public localhost .1.3.6.1.4.1.42.2.2.4.4.1.1.3.0 
      

   These commands should produce output similar to the following:
    
    SDK-DEMO1-MIB::me1SystemLoadAvg1min.0 = STRING: 3.906250e-02 Jobs
    SDK-DEMO1-MIB::me1SystemLoadAvg5min.0 = STRING: 2.734375e-02 Jobs
    SDK-DEMO1-MIB::me1SystemLoadAvg15min.0 = STRING: 3.906250e-02 Jobs