This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: SGML/Notation, Next: SGML/PI, Prev: SGML/Grove, Up: Module List an data type defined in SGML or XML *********************************** NAME ==== SGML::Notation - an data type defined in SGML or XML SYNOPSIS ======== $name = $notation->name; $system_id = $notation->system_id; $public_id = $notation->public_id; $generated_id = $notation->generated_id; $notation->iter; $notation->accept($visitor, ...); The following are defined for type compatibilty: $notation->as_string([$context, ...]); $notation->accept_gi($visitor, ...); $notation->children_accept($visitor, ...); $notation->children_accept_gi($visitor, ...); DESCRIPTION =========== An `SGML::Notation' contains the type definition defined in a document instance, with the possible `generated_id' generated by the parser. Within a grove, any notation with the same name refers to the same `SGML::Notation' object. `SGML::Notation' objects occur as the value of element attributes or as a member of external entities. `$notation->name' returns the name of the notation. `$notation->accept($visitor[, ...])' issues a call back to `$visitor->visit_SGML_Notation($notation[, ...])'. Note that `SGML::Notation' objects are never primary children of an `SGML::Element' object and will not ordinarily occur while simply visiting a grove. `$notation->as_string' returns an empty string. `$notation->accept_gi($visitor[, ...])' is implemented as a synonym for accept. `children_accept' and `children_accept_gi' do nothing. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), Text::EntityMap(3), SGML::Element(3), SGML::PI(3).  File: pm.info, Node: SGML/PI, Next: SGML/SData, Prev: SGML/Notation, Up: Module List an SGML, XML, or HTML document processing instruction ***************************************************** NAME ==== SGML::PI - an SGML, XML, or HTML document processing instruction SYNOPSIS ======== $data = $pi->data; $pi->as_string([$context, ...]); $pi->iter; $pi->accept($visitor, ...); $pi->accept_gi($visitor, ...); $pi->children_accept($visitor, ...); $pi->children_accept_gi($visitor, ...); DESCRIPTION =========== An `SGML::PI' contains the data in a Processing Instruction (PI). `$pi->data' returns the data of the PI object. `$pi->as_string' returns an empty string. `$pi->iter' returns an iterator for the PI object, see `Class::Visitor' for details. `$pi->accept($visitor[, ...])' issues a call back to `$visitor->visit_SGML_PI($sdata[, ...])'. See examples `visitor.pl' and `simple-dump.pl' for more information. `$pi->accept_gi($visitor[, ...])' is implemented as a synonym for accept. `children_accept' and `children_accept_gi' do nothing. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), Text::EntityMap(3), SGML::Element(3), SGML::SData(3), Class::Visitor(3).  File: pm.info, Node: SGML/SData, Next: SGML/SPGroveBuilder, Prev: SGML/PI, Up: Module List an SGML, XML, or HTML document SData replacement ************************************************ NAME ==== SGML::SData - an SGML, XML, or HTML document SData replacement SYNOPSIS ======== $sdata = SGML::SData->new ($replacement[, $entity_name]); $name = $sdata->name; $data = $sdata->data; $sdata->as_string([$context, ...]); $sdata->iter; $sdata->accept($visitor, ...); $sdata->accept_gi($visitor, ...); $sdata->children_accept($visitor, ...); $sdata->children_accept_gi($visitor, ...); DESCRIPTION =========== An `SGML::SData' contains the entity name and replacement value of a character entity reference. `$sdata->name' returns the entity name of the SData object. `$sdata->data' returns the data of the SData object. The Perl module `Text::EntityMap' can be used to map commonly used character entity sets to common output formats. `$sdata->as_string([$context, ...])' returns data surrounded by brackets (`[ ... ]') unless `$context->{sdata_mapper}' is defined, in which case it returns the result of calling the `sdata_mapper' subroutine with data and the remaining arguments. The actual implementation is: &{$context->{sdata_mapper}} ($self->data, @_); `$sdata->iter' returns an iterator for the sdata object, see `Class::Visitor' for details. `$sdata->accept($visitor[, ...])' issues a call back to `$visitor->visit_SGML_SData($sdata[, ...])'. See examples `visitor.pl' and `simple-dump.pl' for more information. `$sdata->accept_gi($visitor[, ...])' is implemented as a synonym for accept. `children_accept' and `children_accept_gi' do nothing. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), Text::EntityMap(3), SGML::Element(3), SGML::PI(3), Class::Visitor(3).  File: pm.info, Node: SGML/SPGroveBuilder, Next: SGML/Simple/BuilderBuilder, Prev: SGML/SData, Up: Module List load an SGML, XML, or HTML document *********************************** NAME ==== SGML::SPGrove - load an SGML, XML, or HTML document SYNOPSIS ======== use SGML::SPGroveBuilder; $grove = SGML::SPGroveBuilder->new ($sysid); $root = $grove->root; $errors = $grove->errors; $entities = $grove->entities; $notations = $grove->notations; Other grove methods defined by SGML::Grove: $grove->as_string([$context, ...]); $grove->iter; $grove->accept($visitor, ...); $grove->accept_gi($visitor, ...); $grove->children_accept($visitor, ...); $grove->children_accept_gi($visitor, ...); DESCRIPTION =========== new loads an SGML, XML, or HTML document instance from `$sysid' using James Clark's SGML Parser (SP), returning a "grove" that contains the root, or top, element of the document, an array of any warnings or errors that may have been generated while parsing the document, and arrays of notations and entities used within the document. `$sysid' is most often the file name of the SGML instance to be parsed, but can be any of the ids described in "System Identifiers" in SP's documentation. For example, `$sysid' can also be a URL, `-' for standard input, a literal string ("`$scalar'"), or a formal system identifier. `$grove->root' returns the `SGML::Element' of the outermost element of the document. `$grove->errors' returns a reference to an array containing any errors generated by SP or SGML::SPGroveBuilder while parsing the document or building the grove. `$grove->entities' returns a reference to a hash containing any entities referenced in this grove (as opposed to entities that may have been declared but not used). `$grove->notations' returns a reference to an array containing any notations referenced in this grove. Refer to SGML::Grove for details of as_string, `iter', accept, `accept_gi', `children_accept', `children_accept_gi'. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3)  File: pm.info, Node: SGML/Simple/BuilderBuilder, Next: SGML/Simple/Spec, Prev: SGML/SPGroveBuilder, Up: Module List build a simple transformation package ************************************* NAME ==== SGML::Simple::BuilderBuilder - build a simple transformation package SYNOPSIS ======== use SGML::SPGroveBuilder; use SGML::Grove; use SGML::Simple::Spec; use SGML::Simple::SpecBuilder; use SGML::Simple::BuilderBuilder; $spec_grove = SGML::SPGroveBuilder->new ($spec_sysid); $spec = SGML::Simple::Spec->new; $spec_grove->accept (SGML::Simple::SpecBuilder->new, $spec); $builder = SGML::Simple::BuilderBuilder->new (spec => $spec [, eval_output => $fh]); $grove = SGML::SPGroveBuilder->new ($sysid); $object_tree_root = My::Object->new(); $grove->accept ($builder->new, $object_tree_root); DESCRIPTION =========== `BuilderBuilder' returns the package name of a package built using a specification read from a specification file. The key `spec' contains the specification. The key ``eval_output'' is either a file handle or a scalar reference, instead of evaluating generated code `BuilderBuilder' will print to or append to ``eval_output'', respectively. Passing a new "builder" to `accept_gi' of a grove will cause an output object tree to be generated under `$object_tree_root' using the builder. `Builder' packages are all singletons, calling new always returns the same object. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), SGML::Simple::Spec(3), SGML::Simple::SpecBuilder(3)  File: pm.info, Node: SGML/Simple/Spec, Next: SGML/Simple/SpecBuilder, Prev: SGML/Simple/BuilderBuilder, Up: Module List a simple transformation specification ************************************* NAME ==== SGML::Simple::Spec - a simple transformation specification SYNOPSIS ======== use SGML::SPGroveBuilder; use SGML::Simple::Spec; use SGML::Simple::SpecBuilder; use SGML::Simple::BuilderBuilder; $spec_grove = SGML::SPGroveBuilder->new ($spec_sysid); $spec = SGML::Simple::Spec->new; $spec_grove->accept (SGML::Simple::SpecBuilder->new, $spec); $builder = SGML::Simple::BuilderBuilder->new (spec => $spec); DESCRIPTION =========== A `SGML::Simple::Spec' object containing `SGML::Simple::Spec::Rule' objects is built by the `SpecBuilder' module from a grove of a simple specification file. `SGML::Simple::Spec' and `SGML::Simple::Spec::Rule' inherit all methods from `Class::Visitor' and `Class::Template'. Fields are defined below. `Spec' objects are passed to `SGML::Simple::BuilderBuilder' to build a Perl package for transforming other SGML groves. `SGML::Simple::Spec' -------------------- `SGML::Simple::Spec' contains the following fields: default_prefix, default_object `default_prefix' defines the default package prefix to be used for objects being created during a transform. `default_object' defines an object to be created when a make field is undefined in a rule. rules -- an array rules contains the global set of rules for this transformation. stuff `stuff' contains extra Perl code to be added as part of the new package. `SGML::Simple::Spec::Rule' -------------------------- `SGML::Simple::Spec::Rule' defines a single transformation rule and contains the following fields: query A space seperated list of generic identifiers that this rule applies to. holder A flag indicating that this element merely contains other elements. No objects are created during the transformation. ignore A flag indicating that this element should be ignored. No objects are created during the transformation and no elements contained in this element are processed. make The package name of an object to be created for this rule. An object in the `make' package is created to hold any elements contained in this element. port A field name in the parent object to append this object to. If not defined, this object is added to the parent's `contents' field. rules -- an array Rules that apply only within the current element. code If code is defined it is used in place of any code that would have been generated by `BuilderBuilder', all other fields are ignored. Code for a holder element looks like this: my $self = shift; my $element = shift; my $parent = shift; $element->children_accept_gi ($self, $parent, @_); Code for creating a new object looks like this: my $self = shift; my $element = shift; my $parent = shift; my $obj = My::Object->new; $parent->push ($obj); $element->children_accept_gi ($self, $obj, @_); Code for switching a set of rules (the current "builder") looks like this: my $self = shift; my $element = shift; my $parent = shift; $new_builder = Another::Builder->new; $element->children_accept_gi ($new_builder, $obj, @_); AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), SGML::Simple::SpecBuilder(3), SGML::Simple::BuilderBuilder(3), Class::Visitor(3), Class::Template(3)  File: pm.info, Node: SGML/Simple/SpecBuilder, Next: SGML/SubDocEntity, Prev: SGML/Simple/Spec, Up: Module List build a SGML::Spec object ************************* NAME ==== SGML::Simple::SpecBuilder - build a SGML::Spec object SYNOPSIS ======== use SGML::SPGroveBuilder; use SGML::Grove; use SGML::Simple::Spec; use SGML::Simple::SpecBuilder; use SGML::Simple::BuilderBuilder; $spec_grove = SGML::SPGroveBuilder->new ($spec_sysid); $spec = SGML::Simple::Spec->new; $spec_grove->accept (SGML::Simple::SpecBuilder->new, $spec); $builder = SGML::Simple::BuilderBuilder->new (spec => $spec); DESCRIPTION =========== `SpecBuilder' builds a new SGML::Spec object from a grove conforming to the "Grove Simple Spec" DTD. The SGML::Spec object can be passed to `SGML::Simple::BuilderBuilder' to create a new package for transforming other groves. See `SGML::Simple::Spec' for more details about the `Spec' object. `SpecBuilder' is a singleton, calling new always returns the same object. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), SGML::Simple::Spec(3), SGML::Simple::BuilderBuilder(3)  File: pm.info, Node: SGML/SubDocEntity, Next: SGML/Writer, Prev: SGML/Simple/SpecBuilder, Up: Module List a SubDoc entity defined in an SGML or XML document ************************************************** NAME ==== SGML::SubDocEntity - a SubDoc entity defined in an SGML or XML document SYNOPSIS ======== $name = $subdoc_entity->name; $data = $subdoc_entity->data; $system_id = $subdoc_entity->system_id; $public_id = $subdoc_entity->public_id; $generated_id = $subdoc_entity->generated_id; $attributes = $subdoc_entity->attributes; $notation = $subdoc_entity->notation; $subdoc_entity->iter; $subdoc_entity->accept($visitor, ...); The following are defined for type compatibilty: $subdoc_entity->as_string([$context, ...]); $subdoc_entity->accept_gi($visitor, ...); $subdoc_entity->children_accept($visitor, ...); $subdoc_entity->children_accept_gi($visitor, ...); DESCRIPTION =========== An `SGML::SubDocEntity' contains a subdoc entity defined in a document instance. Within a grove, any entity with the same name refers to the same `SGML::SubDocEntity' object. `$subdoc_entity->name' returns the entity name of the subdoc entity object. `$subdoc_entity->data' returns the grove object of the subdoc if it has been loaded (XXX but that's not been defined yet). `$subdoc_entity->accept($visitor[, ...])' issues a call back to `$visitor->visit_SGML_SubDocEntity($subdoc_entity[, ...])'. See examples `visitor.pl' and `simple-dump.pl' for more information. `$subdoc_entity->as_string' returns an empty string. `$subdoc_entity->accept_gi($visitor[, ...])' is implemented as a synonym for accept. `children_accept' and `children_accept_gi' do nothing. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), Text::EntityMap(3), SGML::Element(3), SGML::PI(3).  File: pm.info, Node: SGML/Writer, Next: SHA, Prev: SGML/SubDocEntity, Up: Module List write an SGML or XML grove ************************** NAME ==== SGML::Writer - write an SGML or XML grove SYNOPSIS ======== $writer = $SGML::Writer->new ([file_handle => $fh] [, depth => $depth ]); $grove->accept ($writer); DESCRIPTION =========== `SGML::Writer' writes a limited representation of a grove. *file_handle* can be a file handle or a scalar reference, if it is a scalar reference Writer will append to it. Writer writes to standard output if *file_handle* is not specified. XXX this code could do more, see `sgmlnorm(1)' in this node. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), sgmlnorm(1)  File: pm.info, Node: SHA, Next: SNMP/MIB/Compiler, Prev: SGML/Writer, Up: Module List Perl interface to the NIST Secure Hash Algorithm ************************************************ NAME ==== SHA - Perl interface to the NIST Secure Hash Algorithm SYNOPSIS ======== use SHA; $version = &SHA::sha_version; $context = new SHA; $context->reset(); $context->add(LIST); $context->addfile(HANDLE); $digest = $context->digest(); $string = $context->hexdigest(); $digest = $context->hash($string); $string = $context->hexhash($string); DESCRIPTION =========== The `SHA' module is *depreciated*. Use `Digest::SHA1' instead. The current `SHA' module is just a wrapper around the `Digest::SHA1' module. It is provided so that legacy code that rely on the old interface still work. This wrapper does not support the old (and buggy) SHA-0 algorithm. In addition to the methods provided by `Digest::SHA1' this module provide the class methods SHA->hash() and SHA->hexhash() that basically do the same as the sha1() and sha1_hex() functions provided `Digest::SHA1'. The SHA->hex* methods will insert spaces between groups of 8 hex characters, while the Digest::SHA1 version of the same methods will not do this. SEE ALSO ======== *Note Digest/SHA1: Digest/SHA1,  File: pm.info, Node: SNMP/MIB/Compiler, Next: SNMP/Util, Prev: SHA, Up: Module List a MIB Compiler supporting SMIv1 and SMIv2 ***************************************** NAME ==== SNMP::MIB::Compiler - a MIB Compiler supporting SMIv1 and SMIv2 SYNOPSIS ======== use SNMP::MIB::Compiler; my $mib = new SNMP::MIB::Compiler; # search MIBs there... $mib->add_path('./mibs', '/foo/bar/mibs'); # possibly using these extensions... $mib->add_extension('', '.mib', '.my'); # store the compiled MIBs there.. $mib->repository('./out'); # only accept SMIv2 MIBs $mib->{'accept_smiv1'} = 0; $mib->{'accept_smiv2'} = 1; # no debug $mib->{'debug_lexer'} = 0; $mib->{'debug_recursive'} = 0; # store compiled MIBs into files $mib->{'make_dump'} = 1; # read compiled MIBs $mib->{'use_dump'} = 1; # follow IMPORTS clause while compiling $mib->{'do_imports'} = 1; # load a precompiled MIB $mib->load('SNMPv2-MIB'); # compile a new MIB $mib->compile('IF-MIB'); print $mib->resolve_oid('ifInOctets'), "\n"; print $mib->convert_oid('1.3.6.1.2.1.31.1.1.1.10'), "\n"; print $mib->tree('ifMIB'); DESCRIPTION =========== SNMP::MIB::Compiler is a MIB compiler that fully supports both SMI(v1) and SMIv2. This module can be use to compile MIBs (recursively or not) or load already compiled MIBs for later use. Some tasks can be performed by the resulting object such as : - resolution of object names into object identifiers (OIDs). e.g. ifInOctets => 1.3.6.1.2.1.2.2.1.10 - convertion of OIDs. e.g. 1.3.6.1.2.1.2.1 => iso.org.dod.internet.mgmt.mib-2.interfaces.ifNumber - drawing MIB trees. e.g. ifTestTable => ifTestTable | +-- --- ifTestEntry(1) | +-- -rw Integer ifTestId(1) +-- -rw Integer ifTestStatus(2) +-- -rw ObjectID ifTestType(3) +-- -r- Integer ifTestResult(4) +-- -r- ObjectID ifTestCode(5) +-- -rw String ifTestOwner(6) The MIB to be compiled requires no modification. Everything legal according to SMIs is accepted, including MACRO definitions (which are parsed but ignored). This module is shipped with the basic MIBs usually needed by IMPORTS clauses. A lot of IETF MIBs has been successfully tested as well as some private ones. Methods ======= new `SNMP::MIB::Compiler::new()' *class method* To create a new MIB, send a new() message to the SNMP::MIB::Compiler class. For example: my $mib = new SNMP::MIB::Compiler; This will create an empty MIB ready to accept both SMIv1 and SMIv2 MIBs. A lot of attributes can be (des)activated to obtain a more or less strict and verbose compiler. The created object is returned. `add_path' `SNMP::MIB::Compiler::add_path(p1[,p2[,p3]])' *object method* Add one or more directories to the search path. This path is used to locate a MIB file when the 'compile' method is invoqued. The current list of paths is returned. Example: # search MIBs in the "mibs" directory (relative # to cwd) and in "/foo/bar/mibs" (absolute path) $mib->add_path('./mibs', '/foo/bar/mibs'); `add_extension' `SNMP::MIB::Compiler::add_extension(e1[,e2[,e3]])' *object method* Add one or more extensions to the extension list. These extensions are used to locate a MIB file when the 'compile' method is invoqued. All extensions are tested for each directory specified by the add_path() method until one match. The current list of extensions is returned. Example: $mib->add_path('./mibs', '/foo/bar/mibs'); $mib->add_extension('', '.mib'); $mib->compile('FOO'); The order is "./mibs/FOO", "./mibs/FOO.mib", "/foo/bar/mibs/FOO" and "/foo/bar/mibs/FOO.mib". `repository' `SNMP::MIB::Compiler::repository([dir])' *object method* If 'dir' is defined, set the directory where compiled MIBs will be stored (using the compile() method) or loaded (using the load() method). The repository MUST be initialized before a MIB can be compiled or loaded. The current repository is returned. Example: $mib->repository('./out'); print "Current repository is ", $mib->repository, "\n"; compile `SNMP::MIB::Compiler::compile(mib)' *object method* Compile a MIB given its name. All information contained in this MIB is inserted into the current object and is stored into a file in the repository (see the 'make_dump' attribute). The choosen name is the same as the real MIB name (defined in the MIB itself). If a precompiled MIB already exists in the repository and is newer than the given file, it is used instead of a real compilation (see the 'use_dump' attribute). The compiler can be recursive if IMPORTS clauses are followed (see the 'do_imports' attribute) and in that case, uncompiled MIB names must be explict according to paths and extensions critaeria (see add_path() and add_extensions() methods). The current object is returned. load `SNMP::MIB::Compiler::load(mib)' *object method* Load a precompiled MIB given its name. All information contained in this MIB is inserted into the current object. The file is searched in the repository which MUST be initialized. In case of success, returns 1 else returns 0. Example: $mib->load('SNMPv2-SMI'); $mib->load('SNMPv2-MIB'); `resolve_oid' `SNMP::MIB::Compiler::resolve_oid(node)' *object method* Example: print $mib->resolve_oid('ifInOctets'), "\n"; `convert_oid' `SNMP::MIB::Compiler::convert_oid(oid)' *object method* Example: print $mib->convert_oid('1.3.6.1.2.1.31.1.1.1.10'), "\n"; `tree' `SNMP::MIB::Compiler::tree(node)' *object method* Example: print $mib->tree('ifMIB'); Attributes ========== `do_imports' `accept_smiv1' `accept_smiv2' `allow_underscore' `allow_lowcase_hstrings' `allow_lowcase_bstrings' `make_dump' `dumpext' `use_dump' `debug_lexer' `debug_recursive' BUGS ==== Currently, it is more a TODO list than a bug list. - not enough documentation - not enough methods - not enough test scripts - find a better name for compiled MIBs than 'dump's.. even if they are no more than dumps. If your MIBs can't be compiled by this module, please, double check their syntax. If you really think that they are correct, send them to me including their "uncommon" dependencies. AUTHOR ====== Fabien Tassin (fta@oleane.net) COPYRIGHT ========= Copyright 1998, 1999, Fabien Tassin. All rights reserved. It may be used and modified freely, but I do request that this copyright notice remain attached to the file. You may modify this module as you wish, but if you redistribute a modified version, please attach a note listing the modifications you have made.  File: pm.info, Node: SNMP/Util, Next: SOAP, Prev: SNMP/MIB/Compiler, Up: Module List Snmp modules to perform snmp set,get,walk,next,walk_hash etc. ************************************************************* NAME ==== SNMP::Util - Snmp modules to perform snmp set,get,walk,next,walk_hash etc. SYNOPSIS ======== `use SNMP::Util;' ## Documentation (POD) =head1 NAME Perl SNMP utilities - SNMP::Util - Version 1.8 DESCRIPTION =========== This Perl library is a set of utilities for configuring and monitoring SNMP based devices. This library requires the UCD port of SNMP and the SNMP.pm module writted by Joe Marzot. Version 1.0 Initial Release 1.1 Fixed Manifest File 1.2 Added get_hash / walk_hash now calls walk / Modified output in poll_value 1.3 Added use strict to library and fixed some bugs with my vars 1.4 Fixed code to elminate perl warning 1.5 Changed all mapInt functions to mapEnum - (support for mapInt not in Joe Marzot's version 1.8). 1.6 Updated docs html and text 1.7 Includes patches from Charles Anderson 1.8 Includes patches from tyoshida =============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== Software requirements ===================== The following applications need to be built and installed before running the SNMP::Util application. ucd-snmp-3.5 - ftp:://ftp.ece.ucdavis.edu:/pub/snmp/ucd-snmp.tar.gz SNMP-1.8 - www.perl.com/CPAN Summary of functions ==================== get - snmpget and return formatted array get_hash - snmpget and return hash get_set_restore - get value, set new range of values and restore value next - snmpnext and return formatted array ping_check - get uptime and return 1 if reachable ping_check_exit - get uptime and exit if not reachable poll_device - poll a device until it becomes reachable poll_devices - poll several devices until they becomes reachable poll_value - snmpget in a loop until variable reaches desired state set - snmpset and return set_get - snmpset followed by get and check walk - snmpwalk and return formatted array walk_hash - snmpwalk and return hash ($hash->{mibname}{index} = value) Creation on the SNMP::Util object ================================= You must first do a use statement to pull in the library. Then the snmp object can be created. #!/usr/local/lib/perl use lib "put lib path here" use SNMP::Util; The SNMP::Util object is created as follows: $snmp = new SNMP::Util(-device => $IP, -community => $community, -timeout => 5, -retry => 0, -poll => 'on', -poll_timeout => 5, -verbose => 'off', -errmode => 'return', -delimiter => ' ', ) community = snmp community string timeout = snmp timeout in seconds (You may also use sub second values ie 0.5) retry = number of snmp retries on timeouts poll = poll the unreachable device after number of retries reached and then retry again poll timeout = poll timeout in minutes default = 5 minutes verbose = controls the output of the snmp low level library errmode = error mode ('return' on error or 'die' on error) default = return delimeter = specifies the character to use between octets when getting octet-strings Note: Delimiter can also be set by using the setting the Global variable as follows: $SNMP::Util::Delimiter = '-' Creating and using multiple objects ----------------------------------- First populate an array of IP addresses: @IP_array = ('1.1.1.1','1.1.1.2','1.1.1.3','1.1.1.4') foreach $IP (@IP_array){ $snmp->{$IP} = new SNMP::Util(-device => $IP, -community => $community, -timeout => 5, -retry => 0, -poll => 'on', -delimiter => ' ', ) } #Now get the uptime for each switch foreach $IP (@IP_array){ $uptime = $snmp->{$IP}->get('v','sysUpTime.0') print "Uptime for $IP = $uptime\n" } How to use the object for a simple snmpget ========================================== $uptime = $snmp->get('v','sysUpTime.0') where 'v', is the format of the output (v = value) and $uptime contains the system uptime in 10ths of seconds MIB Loading =========== The SNMP::Util module loads the mib using the SNMP::Util_env.pm module by using the following statements. use SNMP::Util_env # Initialize mib &SNMP::initMib() You must update the SNMP::Util_env.pm file or simply set up these environment variables and the SNMP::Util_env.pm file will not override them. The environment variables are as follows: $ENV{'MIBDIRS'} = '/usr/local/lib/snmp/mibs' $ENV{'MIBFILES'} = '/ats/data/mibs/rfc1850.mib: /ats/data/mibs/rfc1406.mib:/ats/data/mibs/rfc1407.mib: /ats/data/mibs/rfc1595.mib:/ats/data/mibs/rfc1724.mib' You can specify whatever MIBS you would like to load. Error Handling method ===================== All error handling is done through the error handling method (error). The error message can be obtained by using the method (errmsg) The detailed error message can be obtained by using the method (errmsg_detail) This error method returns a boolean result to indicate if an error ocurred example: if ($snmp->error){ $error = $snmp->errmsg; $error_detail = $snmp->errmsg_detail; print "snmp error = $error\n"; print "snmp error detail = $error_detail\n"; } Print Output Logging ==================== The printing of output is controlled by the logging routine. the amount of output is configured by setting the MAX_LOG_LEVEL environment variable. There are four levels of output logging: (none,status,fail,debug). You may also set the logging using the global variable Max_log_level. none = print no output (use errmsg only for errors) status = print general status information fail = print general status and failures debug = print general status, failures, and debug information You can set the environment variable in your environment or inside the program using the following format: $env{'MAX_LOG_LEVEL'} = 'debug' or using the global $SNMP::Util::Max_log_level = 'debug' Example Output from Logging: get (noSuchName) There is no such variable name in this MIB. snmpget 100.100.100.1 public 1.3.6.1.2.1.2.2.1.1.1 1.3.6.1.2.1.2.2.1.7.1 snmpget 100.100.100.1 public ifIndex.1 ifAdminStatus.1 snmp error index = 1 Note: error index = the index of the var bind that failed Formatting SNMP output (get, next, walk) ======================================== The SNMP utilities have a formatting function which will format the return values which are most cases an array. The format options are specified as strings as follows: print " format string = oOnNtvei\n" print " o = oid with index\n" print " O = oid without index\n" print " n = name with index\n" print " N = name without index\n" print " t = type\n" print " v = value\n" print " e = enumeration\n" print " i = instance of the mib variable\n\n" Note: enumerations apply to integers and timeticks. It will convert integer values to enumerations and it will convert timeticks to days,hours,minutes,seconds. example usage: @result = $snmp->get('nve','sysUptime.0') $result[0] = sysUptime.0 $result[1] = 13392330 $result[2] = 1 days, 13:12:03 Note: Any format can be used for the (get,walk,next routines) Only 'e' or 'v' is needed in the walk_hash routine. This formatting was designed to allow the user to format the output in whatever format they need for there application. You may want to use the 'v' option when comparing timetick values, but you may want to use the 'e' option for the human readable display. The snmpget routine may be equated to an array if the formatting has more than one value or it may be equated to a scalar value if the formatting has only one value. It must be equated to an array if the snmpget is a multi var bind. Input Formatting ================ The input supplied to the SNMP functions is designed to be very flexible and allows the user to use shortcuts to apply instances to variables. Input formatting options for the get,next,walk ---------------------------------------------- *Simple format name.instance or oid.instance* $snmp->get('e','ifIndex.1','ifAdminStatus.1','ifOperStatus.1') $snmp->get('e','1.3.6.1.2.1.2.2.1.1.1','1.3.6.1.2.1.2.2.1.7.1','1.3.6.1.2.1.2.2.1.8.1') *Shortcut format instance up front (no instance in mib name or oid* $snmp->get('e',1,'ifIndex','ifAdminStatus','ifOperStatus') $snmp->get('e',1,'1.3.6.1.2.1.2.2.1.1','1.3.6.1.2.1.2.2.1.7','1.3.6.1.2.1.2.2.1.8') *Long format name,instance,name,instance etc of oid,instance,oid,instance etc* $snmp->get('e','ifIndex',1,'ifAdminStatus',1,'ifOperStatus',1) $snmp->get('e','1.3.6.1.2.1.2.2.1.1',1,'1.3.6.1.2.1.2.2.1.7',1,'1.3.6.1.2.1.2.2.1.8',1) You may also set up an array for any of the above formats and pass the array into the get function as follows: @oids = ('ifIndex.1','ifAdminStatus.1','ifOperStatus.1') $snmp->get('e',@oids) *Hash like format* name => instance or oid => instance $interface = 1 $snmp->get( 'e', ifIndex => $interface, ifAdminStatus => $interface, ifOperStatus => $interface, ifSpeed => $interface, ) or $snmp->get( index => $interface, ifIndex, ifAdminStatus, ifOperStatus, ifSpeed, ) *Calling get with dashed options* @result = $snmp->get( -format => 'ne', -oids => [ ifIndex => $interface, ifAdminStatus => $interface, ifOperStatus => $interface, ifSpeed => $interface, ], ) or @oids = ('ifIndex.1','ifAdminStatus.1','ifOperStatus.1') @result = $snmp->get( -format => 'ne', -oids => \@oids, ) Note: When using the dashed option format, you must pass the array by reference as shown above. =head2 Input formats for the set routine *Simple format name.instance,value or oid.instance,value* $snmp->set('ifAdminStatus.1','up') $snmp->set('1.3.6.1.2.1.2.2.1.7.1','up') *Shortcut format instance up front (no instance in mib name or oid* $snmp->set(1,'ifAdminStatus','up') $snmp->set(1,'1.3.6.1.2.1.2.2.1.7','up') *Long format name,instance,value or oid,instance,value* $snmp->set('ifAdminStatus',1,'up') $snmp->set('1.3.6.1.2.1.2.2.1.7',1,'up') You may also set up an array for any of the above formats and pass the array into the get method as follows: @oids = ('ifAdminStatus.1','up') $snmp->set(@oids) *Hash like format* $snmp->set( "ifAdminStatus.$interface" => 'up', ) or $snmp->set( index => $interface, "ifAdminStatus" => 'up', ) =head1 SNMP Method summary get --- The get will do a snmpget and return an array specified by the format statement. Usage: @result = $snmp->get('ne','ifAdminStatus.1') $result[0] = ifAdminStatus.1 $result[1] = 'up' $result = $snmp->get('e','ifAdminStatus.1') Note: As shown above, the result is a scalar if only one value is returned get_hash -------- This method will do an snmpget and return a hash. The format for the hash is (value = $hash->{mibname}{index}). example: $hash = $snmp->get_hash('ne','ifIndex.1','ifIndex.2', 'ifOperStatus.1','ifOperStatus.2'); $hash->{ifIndex}{1} = 1 $hash->{ifIndex}{2} = 2 $hash->{ifOperStatus}{1} = up $hash->{ifOperStatus}{2} = up Note: Valid format statements for get_hash are 'ne' or 'nv' =head2 get_set_restore The get_set_restore will get the variable, set it to a range and restore the value Usage: @result = $snmp->get_set_restore('1..10','ifAdminStatus.1'); where the value '1..10' is the range of values Note: The range is specified using .. for ranges and , for individual values. next ---- The next will do a snmpnext and return an array specified by the format statement. Usage: @result = $snmp->next('ne','ifAdminStatus.1') $result[0] = ifAdminStatus.2 $result[1] = 'up' $result = $snmp->next('e','ifAdminStatus.1') Note: As shown above, the result is a scalar if only one value is returned =head2 ping_check The ping_check will do a snmpget of uptime and return 1 if device is alive ping_check_exit --------------- The ping_check will do a snmpget of uptime and exit if not alive poll_device ----------- The poll_device will loop on the snmpget of uptime command until the device is reachable. The loop will exit once the poll_timeout time is reached (default = 5 minutes). poll_devices ------------ The poll_devices will do a snmpget of uptime on several devices until the device are reachable. The loop will exit once the poll_timeout time is reached (default = 5 minutes). $snmp->poll_devices(@IP_array); where @IP_array = array of IP addresses poll_value ---------- The poll value method will poll a mib variable until it reaches that state and returns the amount of time it took to reach that state Usage: $snmp->poll_value(-oid => "ifAdminStatus.$interface", -state => 'up', -timeout => 120, -montime => 5, -delay => 1) or $snmp->poll_value(-oid => "1.3.6.1.2.1.2.2.1.8", -instance => $interface, -state => 'up', -timeout => 120, -montime => 5, -delay => 1) or use a array ref if you want the polling to stop when the result matches more than one value $snmp->poll_value(-oid => "1.3.6.1.2.1.2.2.1.8", -instance => $interface, -state => ['up','down'] -timeout => 120, -montime => 5, -delay => 1) Note: You must use the instance when using oids. set --- The set will set a group of variables and return 1 if passed Usage: @result = $snmp->set( index => 1, ifAdminStatus => 'up', ) set_get ------- The set_get will set a group of variables,get,check and return 1 if passed Usage: @result = $snmp->set( index => 1, ifAdminStatus => 'up', ) walk ---- The walk will do a snmpwalk and return an array specified by the format statement. It also has a special print option to print out each loop in the walk. This method is capable of doing multivarbind walks. Usage: @result = $snmp->walk(-format => 'ne', -oids =>['ifAdminStatus'], -print => 'on'); where print = 'on' or 'off' or use the shortcut format (Note: print will be disabled by default @result = $snmp->walk('ne','ifAdminStatus'); $result[0] = ifAdminStatus.1 $result[1] = 'up' $result[2] = ifAdminStatus.2 $result[3] = 'up' ... walk_hash --------- The walk_hash will do a snmpwalk and return a hash with the value specified by the format. This method is capable of doing multivarbind walks. Usage: $result = $snmp->walk_hash('e','ifIndex','ifAdminStatus','ifOperStatus') $result->{ifIndex}{1} = 1 $result->{ifAdminStatus}{1} = 'up' $result->{ifOperStatus}{1} = 'up' $result->{ifIndex}{2} = 2 $result->{ifAdminStatus}{2} = 'up' $result->{ifOperStatus}{2} = 'up' or Usage: $result = $snmp->walk_hash('v','ifIndex','ifAdminStatus','ifOperStatus') $result->{ifIndex}{1} = 1 $result->{ifAdminStatus}{1} = 1 $result->{ifOperStatus}{1} = 1 $result->{ifIndex}{2} = 2 $result->{ifAdminStatus}{2} = 1 $result->{ifOperStatus}{2} = 1  File: pm.info, Node: SOAP, Next: SOAP/Defs, Prev: SNMP/Util, Up: Module List Library for SOAP clients and servers in Perl ******************************************** NAME ==== SOAP - Library for SOAP clients and servers in Perl SYNOPSIS ======== use SOAP; print "This is SOAP/Perl-$SOAP::VERSION\n"; DESCRIPTION =========== SOAP/Perl is a collection of Perl modules which provides a simple and consistent application programming interface (API) to the Simple Object Access Protocl (SOAP). To learn more about SOAP, see the W3C note at This library provides tools for you to build SOAP clients and servers. The library contains modules for high-level use of SOAP, but also modules for lower-level use in case you need something a bit more customized. SOAP/Perl uses Perl's object oriented features exclusively. There are no subroutines exported directly by these modules. This version of SOAP/Perl supports the SOAP 1.0 specification, which is an IETF internet draft. See for details. The main features of the library are: * Contains various reusable components (modules) that can be used separately or together. * Provides an object oriented model for serializing/deserializing and sending/receiving SOAP packets (lovingly referred to in some circles as SOAP bars). Within this framework we currently support access to SOAP over HTTP, but we're open to expanding support for SOAP over SMTP and other transports in the future. * Provides a fully object oriented interface. * Supports SOAP 1.1 spec. The current version does not yet handle arrays. * Supports serializing/deserializing of sophisticated object graphs which may have cycles (a circular queue would serialize just fine, for instance). * Provides full namespace support for SOAP 1.1, which is recommended by the spec. * Implements full support for SOAP 1.1 references, including correctly dealing with shared references between header and body elements. * Experimental support for extensibility of the serialization/deserialization architecture has been included; see SOAP::TypeMapper for details, and SOAP::Struct and SOAP::StructSerializer for a specific example. * Supports servers using CGI or Apache+mod_perl. Tested with Apache on Linux as well as IIS on Windows 2000. The EnvelopeMaker Object ------------------------ SOAP::EnvelopeMaker takes as input an array of header objects and a single body object (currently these "objects" are either Perl hashes, or instances of SOAP::Struct), and produces as output an XML stream. The Parser Object ----------------- SOAP::Parser takes as input a string (or a file/file handle) and parses the content as a SOAP envelope. This results in an array of header objects and a single body element. To avoid coupling the SOAP serialization/deserialization code to HTTP, a set of loadable transports is also provided. See the following modules for documentation of the transport architecture: SOAP::Transport::HTTP::Client SOAP::Transport::HTTP::Server SOAP::Transport::HTTP::Apache SOAP::Transport::HTTP::CGI Where to Find Examples ---------------------- See SOAP::EnvelopeMaker for a client-side example that shows the serialization of a SOAP request, sending it over HTTP and receiving a response, and the deserialization of the response. See SOAP::Transport::HTTP::Apache for a server-side example that shows how to map incoming HTTP requests to method calls on your own Perl classes. OVERVIEW OF CLASSES AND PACKAGES ================================ This table should give you a quick overview of the classes provided by the library. - High-level classes you should begin with - SOAP::Struct - Ordered collection often used to hold SOAP requests and responses SOAP::TypedPrimitive - Adds an explicit xsi:type to stream SOAP::EnvelopeMaker - Serializes objects into SOAP bars SOAP::Parser - Deserializes SOAP bars into objects SOAP::Transport - Description of transport architecture SOAP::Transport::HTTP - Description of HTTP transport SOAP::Transport::HTTP::Client - Client side support for HTTP, using libwww-perl SOAP::Transport::HTTP::Server - Server side support for HTTP, decoupled from web server APIs SOAP::Transport::HTTP::Apache - Apache/mod_perl support SOAP::Transport::HTTP::CGI - Vanilla CGI support - Serialization architecture - SOAP::Envelope -- Low level access to SOAP serialization SOAP::OutputStream -- used in conjunction with SOAP::Envelope for Low level access to SOAP serialization SOAP::Packager -- Helps to implement SOAP 1.0 packages, used by SOAP::Envelope and SOAP::OutputStream SOAP::GenericHashSerializer -- Generic serializer for Perl hash references SOAP::GenericScalarSerializer -- Generic serializer for Perl scalars SOAP::TypedPrimitiveSerializer -- Specialized serializer SOAP::StructSerializer -- Specialized serializer - Deserialization architecture - SOAP::GenericInputStream.pm -- Look here if you are interested in extending the deserialization framework to be able to deserialize your own objects -- Miscellaneous -- SOAP::TypeMapper -- An experimental extensibility point for the serialization architecture SOAP::Defs -- Constants used by the other modules MORE DOCUMENTATION ================== All modules contain detailed information on the interfaces they provide. BUGS AND LIMITATIONS ==================== The serialization framework does not yet handle arrays, and the HTTP transport does not handle M-POST. ACKNOWLEDGEMENTS ================ Keith Brown is the original and current author of this work, but he worked very closely with Don Box in developing a common design and implementation architecture (Don was building a Java implementation side-by-side, and Keith and Don worked together in a kind of XP style of programming - it was fun). GopalK at Microsoft was tremendously helpful in ferreting out issues in the SOAP spec. Mike Abercrombie at DevelopMentor (where Keith and Don work) was very supportive of the effort as well. Thanks Mike! COPYRIGHT ========= Copyright 1999-2000, DevelopMentor. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AVAILABILITY ============ The latest version of this library is normally available from CPAN as well as: http://soapl.develop.com/soap_perl_current The best place to discuss this code is on the SOAP mailing list at: http://discuss.develop.com/soap.html  File: pm.info, Node: SOAP/Defs, Next: SOAP/Envelope, Prev: SOAP, Up: Module List Spec-defined constants ********************** NAME ==== SOAP::Defs - Spec-defined constants SYNOPSIS ======== use SOAP::Defs; DESCRIPTION =========== This is an internal class that exports global symbols needed by various SOAP/Perl classes. You don't need to import this module directly unless you happen to be building SOAP plumbing (as opposed to simply writing a SOAP client or server). AUTHOR ====== Keith Brown