Compaq TCP/IP Services for OpenVMS Programming And Reference Manual
  1. Manuals
  2. Brands
  3. Compaq Manuals
  4. Software
  5. Compaq TCP/IP Services for OpenVMS
  6. Programming and reference manual
Compaq TCP/IP Services for OpenVMS Programming And Reference Manual

Compaq TCP/IP Services for OpenVMS Programming And Reference Manual

Tcp/ip services for openvms
Hide thumbs
Table of Contents

Advertisement

Quick Links

Download this manual
Compaq TCP/IP Services for
OpenVMS
SNMP Programming and
Reference
Order Number: AA–R04BC–TE
January 2001
Revision/Update Information:
Software Version:
Operating Systems:
Compaq Computer Corporation
Houston, Texas
This manual supersedes the DIGITAL
TCP/IP Services for OpenVMS eSNMP
Programming and Reference, Version
5.0.
Compaq TCP/IP Services for OpenVMS
Version 5.1
OpenVMS Alpha Versions 7.1, 7.2-1
OpenVMS VAX Versions 7.1, 7.2

Advertisement

Table of Contents
loading
Need help?

Need help?

Do you have a question about the Compaq TCP/IP Services for OpenVMS and is the answer not in the manual?

Questions and answers

Related Manuals for Compaq Compaq TCP/IP Services for OpenVMS

Summary of Contents for Compaq Compaq TCP/IP Services for OpenVMS

  • Page 1 January 2001 This manual supersedes the DIGITAL Revision/Update Information: TCP/IP Services for OpenVMS eSNMP Programming and Reference, Version 5.0. Compaq TCP/IP Services for OpenVMS Software Version: Version 5.1 OpenVMS Alpha Versions 7.1, 7.2-1 Operating Systems: OpenVMS VAX Versions 7.1, 7.2...
  • Page 2 Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license. Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice.

  • Page 3: Table Of Contents

    Contents Preface ............1 Overview SNMP Architecture .
  • Page 4 4 Using the SNMP Utilities Using the MIB Browser ........4–1 4.1.1 MIB Browser Parameters .
  • Page 5 cmp_oid_prefix ..........5–48 clone_oid .

  • Page 7: Preface

    Preface The Compaq TCP/IP Services for OpenVMS product is the Compaq implementation of the TCP/IP networking protocol suite and internet services for OpenVMS Alpha and OpenVMS VAX systems. A layered software product, TCP/IP Services provides a comprehensive suite of functions and applications that support industry-standard protocols for heterogeneous network communications and resource sharing.

  • Page 8: Tcp/Ip Services Documentation

    DIGITAL TCP/IP Services for This manual provides conceptual information about networking OpenVMS Concepts and Planning and the TCP/IP protocol including a description of the Compaq implementation of the Berkeley Internet Name Domain (BIND) service and the Network File System (NFS). It outlines general planning issues to consider before configuring your system to use...
  • Page 9 For a comprehensive overview of the TCP/IP protocol suite. you might find the book Internetworking with TCP/IP: Principles, Protocols, and Architecture, by Douglas Comer, useful. Reader’s Comments Compaq welcomes your comments on this manual. Please send comments to either of the following addresses: Internet openvmsdoc@compaq.com...
  • Page 10 The following conventions are used in this manual. In addition, please note that all IP addresses are fictitious. Ctrl/x A sequence such as Ctrl/x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
  • Page 11 Monospace text Monospace type indicates code examples and interactive screen displays. This typeface indicates UNIX system output or user input, commands, options, files, directories, utilities, hosts, and users. In the C programming language, this typeface identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

  • Page 13: Overview

    (API), tools used to build additional subagents, startup and shutdown procedures, and text-based configuration files. This chapter provides an overview of the Compaq implementation of eSNMP. Topics include: •...

  • Page 14: Request Handling

    The master agent and subagents communicate by means of the AgentX protocol, which is based on RFC 2741. For information about configuring and managing the SNMP service, refer to the Compaq TCP/IP Services for OpenVMS Management guide. 1.2 Request Handling The eSNMP software manages network communication by having the master agent listen for requests and then passes the requests to the appropriate subagent.

  • Page 15: Esnmp Data Flow

    Overview 1.2 Request Handling Figure 1–2 eSNMP Data Flow NMS1 Host 1 Subagent 1 Client Subagent 2 Master Agent Network Subagent n NMS2 Host 2 Client Master Agent Subagent 1 Trap client Legend: Flow of trap notification Flow of get/set request Flow of "are_you_there"...

  • Page 16: Tcp/Ip Services Components For Snmp

    Overview 1.2 Request Handling The network management station sends an SNMP request to the master agent running on the host, using port 161. An SNMP request is made using one of the following commands: • • GetNext • GetBulk • Note TCP/IP Services does not support the standard SNMP command.

  • Page 17: Writing An Esnmp Subagent

    Overview 1.3 TCP/IP Services Components for SNMP Table 1–1 (Cont.) SNMP Component Files File Location Function TCPIP$SNMP_TRAPRCV.EXE SYS$SYSTEM Utility for receiving trap messages. TCPIP$ESNMP_SHR.EXE SYS$SHARE Image file containing eSNMP application programming interface (API) routines. TCPIP$SNMP_STARTUP.COM SYS$STARTUP Command procedure that installs master and subagent images and runs TCPIP$SNMP_RUN.COM.

  • Page 18: The Esnmp Api

    For information about building a subagent on an OpenVMS system, see Chapter 3. 1.5 The eSNMP API The Compaq TCP/IP Services for OpenVMS implementation of the eSNMP architecture includes an API that provides programmers with many eSNMP routines they would otherwise have to develop themselves.

  • Page 19: The Snmp Utilities

    Overview 1.5 The eSNMP API Interface routines handle the basic subagent operations, such as: • Subagent initialization and termination • Registration • Polling of the master agent • Trap sending • UNIX system time conversion • Adding and removing subagent capabilities registered with the master agent The support routines allow the subagent to manipulate the data in the response to the request, and include the following: •...

  • Page 20: Snmp Versions

    Overview 1.6 The MIB Compiler • Method routine function prototypes The subtree_TBL.C file is an object file that contains the following: • An array of integers representing the OIDs for each MIB variable • An array of OBJECT structures • An initialized SUBTREE structure 1.7 SNMP Versions The extensible SNMP software supports SNMP Version 2, based on RFCs 1901...

  • Page 21: For More Information

    This manual provides the OpenVMS information required for implementing eSNMP subagents and ensuring their proper operation in that environment. The eSNMP software for OpenVMS is derived from the Compaq Tru64 UNIX product. For information about the architecture and for details about the eSNMP API, refer to the UNIX documentation at the following URL: http://www.compaq.com/unix...

  • Page 23: Mibs Provided With Tcp/Ip Services

    MIBs Provided with TCP/IP Services This chapter describes how MIBs are implemented on OpenVMS. The MIBs provided with TCP/IP Services are: • The Host Resources MIB, which manages operating system objects (Section 2.1) • MIB II, which manages TCP/IP kernel objects (Section 2.2) 2.1 Overview of the Host Resources MIB The Host Resources MIB defines a uniform set of objects useful for the management of host computers.
  • Page 24 MIBs Provided with TCP/IP Services 2.1 Overview of the Host Resources MIB Table 2–1 (Cont.) Host Resources MIB Objects Object Name RFC Description OpenVMS Description hrSystemProcesses Number of process contexts Number of processes listed using the currently loaded or running SHOW SYSTEM command.

  • Page 25: Restrictions To Host Resources Mib

    MIBs Provided with TCP/IP Services 2.1 Overview of the Host Resources MIB Table 2–1 (Cont.) Host Resources MIB Objects Object Name RFC Description OpenVMS Description hrNetworkIfIndex The value of the ifIndex that The value of the index in the interface corresponds to this network table in the standard MIB that device.
  • Page 26 MIBs Provided with TCP/IP Services 2.1 Overview of the Host Resources MIB hrFSLastFullBackupDate hrFSLastPartialBackupDate hrStorageSize hrSWRunStatus hrSystemDate hrSystemInitialLoadDevice hrSystemInitialLoadParameters Note For objects that are not implemented, the Host Resources MIB returns a error status. NoSuchObject TCP/IP Services supports the objects in the Host Resources MIB as follows: •...

  • Page 27: Overview Of Mib

    MIBs Provided with TCP/IP Services 2.1 Overview of the Host Resources MIB TCPIP$SNMP_REQUEST.EXE responds with no output and returns directly to the DCL prompt. After an NFS mount, the following information is returned in response to a request. The data items implemented for OpenVMS (refer to RFC 1514) are: –...

  • Page 28: Mib Ii Implemented Groups

    MIBs Provided with TCP/IP Services 2.2 Overview of MIB II 2.2.1 MIB II Implemented Groups A group is a subdivision of a MIB that defines a subtree. SNMP as implemented by TCP/IP Services supports the following groups: • system (1) •...
  • Page 29 MIBs Provided with TCP/IP Services 2.2 Overview of MIB II When both the TCPIP$OS_MIBS and TCPIP$HR_MIB subagents are running, a request on the sysORTable is as follows. Except where noted, the OIDs conform to RFC 1907. 1.3.6.1.2.1.1.9.1.2.1 = 1.3.6.1.4.1.36.15.3.3.1.1 1.3.6.1.2.1.1.9.1.2.2 = 1.3.6.1.4.1.36.15.3.3.1.2 1.3.6.1.2.1.1.9.1.3.1 = Base o/s agent (OS_MIBS) capabilities 1.3.6.1.2.1.1.9.1.3.2 = Base o/s agent (HR_MIB) capabilities 1.3.6.1.2.1.1.9.1.4.1 = 31 = 0 d 0:0:0...

  • Page 31: Creating A Subagent Using The Esnmp Api

    Creating a Subagent Using the eSNMP API This chapter describes how to use the eSNMP API to create a MIB subagent that manages entities or applications. Topics included in this chapter are: • Creating a MIB specification (Section 3.1) • The structure of management information (Section 3.2) •...

  • Page 32: Assigning Object Identification Codes

    Creating a Subagent Using the eSNMP API 3.2 The Structure of Management Information 3.2.1 Assigning Object Identification Codes Each object in a MIB is associated with an identifier of the ASN.1 type, called an object identifier (OID). OIDs are unique integers that follow a hierarchical naming convention.

  • Page 33: Mib Ii In Smi Tree Structure

    Creating a Subagent Using the eSNMP API 3.2 The Structure of Management Information Figure 3–1 MIB II in SMI Tree Structure iso (1) org (3) dod (6) internet (1) directory (1) mgmt (2) mib2 (1) system (1) interfaces (2) at (3) ip (4) icmp (5) tcp (6)
  • Page 34 Creating a Subagent Using the eSNMP API 3.2 The Structure of Management Information For example, the chess MIB provided with the sample code in the [TCPIP$EXAMPLES.SNMP] directory has an element with the name ‘‘chess.’’ The OID for the element chess is 1.3.6.1.4.1.36.2.15.2.99, which is derived from its position in the hierarchy of the tree: iso(1) org(3)

  • Page 35: Creating A Mib Source File

    Creating a Subagent Using the eSNMP API 3.2 The Structure of Management Information Normally, it is the nonleaf nodes that are registered as a subtree with the master agent. However, leaf nodes, or even specific instances, can be registered as a subtree.
  • Page 36 Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source File The parameters and qualifiers for the MIBCOMP command are as follows: Parameter or Qualifier Definition MIB-source-file A comma-separated list of MIB definition files. The standard extension is .MY, but you can specify any valid OpenVMS file name.

  • Page 37: Unix Utilities Supplied With Tcp/Ip Services

    These modules are created by the MIBCOMP command or the UNIX utilities. Compaq recommends that you do not edit them. If the MIBs change or if a future version of the SNMP development utilities requires your object tables to be rebuilt, it is easier to rebuild and recompile the files if you did not edit them.
  • Page 38 Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source File 1. Declaration Section The first section of the subtree_TBL.H file is a declaration of the subtree structure. The subtree is automatically initialized by code in the subtree_TBL.C file.

  • Page 39: The Subtree_Tbl.c Output Files

    Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source File typedef struct _chess_type { ches; chessMaxGames; chessNumGames; char chessProductID_mark; char chessMaxGames_mark; char chessNumGames_mark; } chess_type; Although MIB group structures are provided for your use, you are not required to use them.
  • Page 40 Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source File 2. Array of OBJECT Structures Section The second section of the subtree_TBL.C file is an array of OBJECT structures. Each MIB variable within the subtree has one OBJECT. The chess example produces the following: static OBJECT objects[] = { {I_chessProductID...

  • Page 41: Including The Routines And Building The Subagent

    Creating a Subagent Using the eSNMP API 3.3 Creating a MIB Source File 3. Initialized Subtree Structure Section The third section of the subtree_TBL.C file is the SUBTREE structure itself. A pointer to this structure is passed to the eSNMP library routine esnmp_register to register the subtree.

  • Page 42: Including Extension Subagents In The Startup And Shutdown Procedures

    Creating a Subagent Using the eSNMP API 3.4 Including the Routines and Building the Subagent Depending on the version of the Compaq C compiler you are using, you might see warnings that you can ignore. Portions of these warnings are as follows:...
  • Page 43 Creating a Subagent Using the eSNMP API 3.5 Including Extension Subagents in the Startup and Shutdown Procedures File Name Edit Required TCPIP$EXTENSION_MIB_SHUTDOWN.COM Edit the example lines to: • Include symbols for the detached processes that are running custom images. Use the same process names specified in TCPIP$EXTENSION_MIB_ RUN.COM.

  • Page 45: Using The Snmp Utilities

    Using the SNMP Utilities TCP/IP Services includes the following programs, which are useful for testing applications and for analyzing SNMP problems: • TCPIP$SNMP_REQUEST (MIB browser) (Section 4.1) • TCPIP$SNMP_TRPSND (trap sender) (Section 4.2) • TCPIP$SNMP_TRPRCV (trap receiver) (Section 4.2) These programs can be invoked by commands that are defined by the SYS$STARTUP:TCPIP$DEFINE_COMMANDS.COM command procedure.

  • Page 46: Mib Browser Flags

    Using the SNMP Utilities 4.1 Using the MIB Browser Table 4–1 (Cont.) snmp_request Command Parameters Parameter Function "community" The community string to be used in the query. This parameter is case sensitive. Typically, agents are configured to permit read access to the community string "public".

  • Page 47: Flags For The Snmp_Request Command

    Using the SNMP Utilities 4.1 Using the MIB Browser Table 4–2 Flags for the snmp_request Command Flag Description Specifies hexadecimal dump mode. Before displaying a return value, displays a hexadecimal dump of SNMP packets sent and received. For example: $ snmp_request host1 "public" getnext -d -v 2c 1.3.6.1.6.3.1.1.6 Sent: 30290201 01040670 75626C69 63A11C02 0)..public...
  • Page 48 Using the SNMP Utilities 4.1 Using the MIB Browser Table 4–2 (Cont.) Flags for the snmp_request Command Flag Description Specifies loop mode. Note that this flag is the letter l, not the number 1. Valid only if request-type GetNext GetBulk (where flag is set to 0, and flag...

  • Page 49: Mib Browser Data Types

    Using the SNMP Utilities 4.1 Using the MIB Browser Table 4–2 (Cont.) Flags for the snmp_request Command Flag Description -s sleep_interval Specifies the number of seconds between iterations of sending a request (for the flag) and listening for a reply (for the ) flag.

  • Page 50: Command Examples For Snmp_Request

    Using the SNMP Utilities 4.1 Using the MIB Browser Note Except for (Counter64), the data types are case sensitive. To preserve uppercase for display strings and NULL, enclose the value in double quotation marks. For example, ‘‘– ’’ or ‘‘– ’’.
  • Page 51 Using the SNMP Utilities 4.1 Using the MIB Browser $ snmp_request marley.dec.com "public" get 1.3.6.1.2.1.2.2.1.2.1 - _$ 1.3.6.1.2.1.25.1.1.0 1.3.6.1.2.1.2.2.1.2.1 = LO IP Interface: LO0, OpenVMS Adapter: <none>, Loopback Port 1.3.6.1.2.1.25.1.1.0 = 6024942 = 0 d 16:44:9 3. The following example shows how to retrieve the next MIB II variable. This is similar to the command in example 1, except that a GetNext request is...

  • Page 52: Using The Trap Sender And Trap Receiver Programs

    Using the SNMP Utilities 4.1 Using the MIB Browser 6. The following example uses the same command as in example 5, but it specifies the flag instead of the flag. Only OIDs with the prefix matching the input OID are returned. Note that as with other getnext request examples, the value for the input OID is not returned.

  • Page 53: Entering Commands For The Trap Sender Program

    Using the SNMP Utilities 4.2 Using the Trap Sender and Trap Receiver Programs By default, these programs use UDP port 162. However, you can specify another port with the flag or set up an SNMP-trap service that specifies the port you want to use.

  • Page 54: Trap Sender Flags

    Using the SNMP Utilities 4.2 Using the Trap Sender and Trap Receiver Programs Table 4–4 Parameters for the snmp_trapsnd Command Parameter Description enterprise For SNMP Version 1, specifies the enterprise object identifier (OID) on whose behalf the trap is being sent. For example, 1.3.6.1.4.1.1. If you specify 0 or 0.0, the null OID (0.0) is sent.

  • Page 55: Trap Sender Examples

    Using the SNMP Utilities 4.2 Using the Trap Sender and Trap Receiver Programs Table 4–5 (Cont.) Flags for the snmp_trapsnd Command Flag Description -h host Specifies the host name or IP address (in ASN.1 dot notation format) of the localhost destination host to receive the trap message.

  • Page 56: Entering Commands For The Trap Receiver Program

    Using the SNMP Utilities 4.2 Using the Trap Sender and Trap Receiver Programs enterprise - 1.2.3 agent address - 6.20.208.53 trap type - Enterprise-specific (6) enterprise-specific value - (33) timeticks - 100 4.2.2 Entering Commands for the Trap Receiver Program The trap receiver program lets you listen for, receive, and display SNMP trap messages.

  • Page 57: Trap Receiver Examples

    Using the SNMP Utilities 4.2 Using the Trap Sender and Trap Receiver Programs account that has SYSPRV privilege. Note that the port number must be greater than zero. 4.2.2.3 Trap Receiver Examples 1. The following example requests trap information on a system that does not have traps configured and does not have SYSPRV privilege or sufficient privilege.

  • Page 59: Esnmp Api Routines

    eSNMP API Routines This chapter provides reference information about the following types of application programming interface (API) routines in the eSNMP developer’s kit: • Interface routines (Section 5.1) • Method routines (Section 5.2) • Support routines (Section 5.3) 5.1 Interface Routines The interface routines are for developers writing the portion of the application programming interface (API) that handles the connection between the agent and the subagent.

  • Page 60: Esnmp_Init

    eSNMP API Routines esnmp_init esnmp_init Initializes the Extensible SNMP (eSNMP) subagent and initiates communication with the master agent. Format int esnmp_init (int *socket, char *subagent_identifier ) ; Arguments socket The address of the integer that receives the socket descriptor used by eSNMP. subagent_identifier The address of a null-terminated string that uniquely identifies this subagent (usually a program name).

  • Page 61: Esnmp_Register

    The number of seconds the master agent should wait for responses when requesting data in this subtree. This value must be between 0 (zero) and 300. If the value is 0, the default timeout is 3 seconds. Compaq recommends that you use the default. For information about modifying the default subagent timeout value, refer to Section 6.2.
  • Page 62 eSNMP API Routines esnmp_register A subtree is identified by the base MIB name and the corresponding number of the node that is the parent of all MIB variables contained in the subtree. For example: The MIB II subtree has an .
  • Page 63 eSNMP API Routines esnmp_register status = esnmp_register( &ipRouteEntry_subtree, RESPONSE_TIMEOUT, REGISTRATION_PRIORITY ); if (status != ESNMP_LIB_OK) { printf ("Could not queue the ’ipRouteEntry’ \n"); printf ("subtree for registration\n"); eSNMP API Routines 5–5...
  • Page 64 eSNMP API Routines esnmp_unregister esnmp_unregister Cancels registration of a MIB subtree previously registered with the master agent. Format int esnmp_unregister ( SUBTREE *subtree ) ; Arguments subtree A pointer to a subtree structure corresponding to the subtree to be handled. The code emitted by the MIB compiler files (subtree_TBL.C and subtree_TBL.H) externally declare and initialize the subtree structures.

  • Page 65: Esnmp_Register2

    eSNMP API Routines esnmp_register2 esnmp_register2 Requests registration of a single MIB subtree. This indicates to the master agent that the subagent instantiates MIB variables within the registered MIB subtree. routine offers extensions to the routine. esnmp_register2 esnmp_register Format int esnmp_register2 ( ESNMP_REG *reg ) ; Arguments A pointer to an ESNMP_REG structure that contains the following fields: Field Name...
  • Page 66 eSNMP API Routines esnmp_register2 Field Name Description range_upper_bound An integer value that, with a nonzero range_subid field, specifies a range instead of one of the MIB subtree’s OID subidentifiers. The range_upper_bound field provides the upper bound of the range and the range_subid field provides the lower bound of the range, which is the MIB subtree’s OID subidentifier.
  • Page 67 eSNMP API Routines esnmp_register2 When restarting the eSNMP protocol by calling , all MIB subtree esnmp_init registrations are cleared. All MIB subtrees must be reregistered. A MIB subtree is identified by the base MIB variable name and its corresponding OID. This tuple represents the parent of all MIB variables that are contained in the MIB subtree;...

  • Page 68: Esnmp_Unregister2

    eSNMP API Routines esnmp_register2 Example #include <esnmp.h> #define RESPONSE_TIMEOUT /* use the default time set in esnmp_init message */ #define REGISTRATION_PRIORITY /* priority at which the MIB subtree will register */ #define RANGE_SUBID /* the identifier position in oid->elements just after mib-2 */ #define RANGE_UPPER_BOUND /* the identifier for egp, under mib-2 */...
  • Page 69 eSNMP API Routines esnmp_unregister2 esnmp_unregister2 Cancels registration of a MIB subtree previously established with the master agent. Use this routine only when the MIB subtree was registered using the routine. esnmp_register2 Format int esnmp_unregister2 ( ESNMP_REG *reg ) ; Arguments A pointer to the ESNMP_REG structure that was used when the esnmp_register2 routine was called.
  • Page 70 eSNMP API Routines esnmp_capabilities esnmp_capabilities Adds a subagent’s capabilities to the master agent’s . The sysORTable sysORTable is a conceptual table that contains an agent’s object resources, and is described in RFC 1907. Format void esnmp_capabilities ( OID *agent_cap_id, char *agent_cap_descr ) ; Arguments agent_cap_id A pointer to an object identifier that represents an authoritative agent capabilities...

  • Page 71: Esnmp_Capabilities

    eSNMP API Routines esnmp_uncapabilities esnmp_uncapabilities Removes a subagent’s capabilities from the master agent’s sysORTable Format void esnmp_uncapabilities ( OID *agent_cap_id ) ; Arguments agent_cap_id A pointer to an object identifier that represents an authoritative agent capabilities identifier. This value is used for the object in the for the sysORID...

  • Page 72: Esnmp_Poll

    eSNMP API Routines esnmp_poll esnmp_poll Processes a pending message that was sent by the master agent. Format int esnmp_poll ( ) Description This routine is called after the select( ) call has indicated data is ready on the eSNMP socket. (This socket was returned from the call to the esnmp_init routine.) If a received message indicates a problem, an entry is made to the SNMP log file...

  • Page 73: Esnmp_Are_You_There

    eSNMP API Routines esnmp_are_you_there esnmp_are_you_there Requests the master agent to report immediately that it is up and functioning. Format int esnmp_are_you_there ( ) ; Description esnmp_are_you_there routine does not block waiting for a response. The routine is intended to cause the master agent to reply immediately. The response should be processed by calling the routine.

  • Page 74: Esnmp_Trap

    eSNMP API Routines esnmp_trap esnmp_trap Sends a trap message to the master agent. Format int esnmp_trap ( int *generic_trap, int specific_trap, char *enterprise, varbind *vb ) 2 ; Arguments generic_trap A generic trap code. Set this argument value to 0 (zero) for SNMPv2 traps. specific_trap A specific trap code.

  • Page 75: Esnmp_Term

    eSNMP API Routines esnmp_term esnmp_term Sends a close message to the master agent and shuts down the subagent. Format void esnmp_term (void) ; Description Subagents must call this routine when terminating so that the master agent can update its MIB registry quickly and so that resources used by eSNMP on behalf of the subagent can be released.

  • Page 76: Esnmp_Sysuptime

    eSNMP API Routines esnmp_sysuptime esnmp_sysuptime Converts UNIX system time obtained from into a value with the gettimeofday same time base as sysUpTime Format unsigned int esnmp_sysuptime ( struct timeval *timestamp ) ; Argument timestamp A pointer to , which contains a value obtained from the struct timeval system call.

  • Page 77: Method Routines

    eSNMP API Routines 5.2 Method Routines 5.2 Method Routines SNMP requests may contain many encoded MIB variables. The code libsnmp executing in a subagent matches each with an object table VariableBinding entry. The object table’s method routine is then called. Therefore, a method routine is called to service a single MIB variable.

  • Page 78: Get Routine

    eSNMP API Routines *_get Routine *_get Routine The *_get routine is a method routine for the specified MIB item, which is typically a MIB group (for example, system in MIB II) or a table entry (for example, in MIB II). ifEntry Format int mib-group_get ( METHOD *method ) ;...
  • Page 79 eSNMP API Routines *_get Routine Field Name Description object A pointer to the object table entry for the MIB variable being referenced. The method->object->object_index field is this object’s unique index within the object table (useful when one method routine services many objects).

  • Page 80: Set Routine

    eSNMP API Routines *_set Routine *_set Routine method routine for a specified MIB item, which is typically a MIB *_set group (for example, system in MIB II) or a table entry (for example, ifEntry MIB II). Format int mib-group_set ( METHOD *method ) ; Arguments method A pointer to a METHOD structure that contains the following fields:...
  • Page 81 eSNMP API Routines *_set Routine Field Name Description A pointer to a ROW_CONTEXT structure (defined in the ESNMP.H header file). All requests to the method routine that refer to the same group and that have the same instance number will be presented with the same row structure.

  • Page 82: Processing *_Set Routines

    eSNMP API Routines *_set Routine Return Values ESNMP_MTHD_noError The routine completed successfully. ESNMP_MTHD_notWritable The requested object cannot be set or was not implemented. ESNMP_MTHD_wrongType The data type for the requested value is the wrong type. ESNMP_MTHD_ The requested value is the wrong length. wrongLength ESNMP_MTHD_ The requested value is represented incorrectly.
  • Page 83 eSNMP API Routines *_set Routine If any row reports failure, all rows that were successfully committed are told to undo the phase. This is accomplished by calling a single method routine for each row (the same one that was called for the commit phase), with a method->action equal to ESNMP_ACT_UNDO.

  • Page 84: Method Routine Applications Programming

    eSNMP API Routines *_set Routine • ESNMP_ACT_UNDO For each conceptual row that was successfully committed, the same method routine is called with method->action equal to ESNMP_ACT_UNDO. The ROW_CONTEXT structures that have not yet been called for the COMMIT phase are not called for the UNDO phase; they are called for CLEANUP phase.

  • Page 85: Value Representation

    eSNMP API Routines *_set Routine • Load the response OID back into the method routine’s VARBIND structure. Set the method->varbind field with the OID of the actual MIB variable instance you are returning. This is usually accomplished by loading an array of integers with the instance OID you wish to return and calling the instance2OID support routine.
  • Page 86 eSNMP API Routines *_set Routine The displaystring is different only in that the character array can be interpreted as ASCII text, but the octetstring can be anything. If the octetstring contains bits or a bit string, the OCT structure contains the following: A length equal to the number of bytes needed to contain the value that is ((qty-bits - 1)/8 + 1)
  • Page 87 eSNMP API Routines *_set Routine • ESNMP_TYPE_Integer32 ESNMP_TYPE_Counter32 ESNMP_TYPE_<Gauge32 (varbind->value.ul field) The 32-bit counter and 32-bit gauge data types are stored in the VARBIND structure as an unsigned integer. Use the o_integer function to insert an unsigned value into the VARBIND structure.

  • Page 88: Support Routines

    eSNMP API Routines 5.3 Support Routines 5.3 Support Routines The support routines are provided as a convenience for developers writing method routines that handle specific MIB elements. The following support routines are provided: Routine Function o_integer Loads an integer value. Loads an octet value.

  • Page 89: O_Integer

    eSNMP API Routines o_integer o_integer Loads an integer value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure. Format int o_integer ( VARBIND *vb, OBJECT *obj, unsigned long value ); Arguments A pointer to the VARBIND structure that is supposed to receive the data. A pointer to the structure for the MIB variable associated with the OBJECT...
  • Page 90 eSNMP API Routines o_integer Example #include <esnmp.h> #include "ip_tbl.h" <-- for ipNetToMediaEntry_type definition VARBIND = method->varbind; OBJECT *object = method->object; ipNetToMediaEntry_type *data; : assume buffer and structure member assignments occur here switch(arg) { case I_atIfIndex: return o_integer(vb, object, data->ipNetToMediaIfIndex); 5–32 eSNMP API Routines...

  • Page 91: O_Octet

    eSNMP API Routines o_octet o_octet Loads an octet value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure. Format int o_octet ( VARBIND *vb, OBJECT *obj, unsigned long value ); Arguments A pointer to the VARBIND structure that is supposed to receive the data. If the original value in the vb field is not null, this routine attempts to free it.

  • Page 92: O_Oid

    eSNMP API Routines o_oid o_oid Loads an value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure. Format int o_oid ( VARBIND *vb, OBJECT *obj, OID *oid ); Arguments A pointer to the VARBIND structure that is supposed to receive the data. If the original value in the VARBIND structure is not null, this routine attempts to free it.

  • Page 93: O_String

    eSNMP API Routines o_string o_string Loads a string value into the VARBIND structure with the appropriate type. This function does not allocate the VARBIND structure. Format int o_string ( VARBIND *vb, OBJECT *obj, unsigned character *ptr, int len ); Arguments A pointer to the VARBIND structure that is supposed to receive the data.
  • Page 94 eSNMP API Routines o_string Example #include <esnmp.h> #include "ip_tbl.h" <-- for ipNetToMediaEntry_type definition VARBIND = method->varbind; OBJECT *object = method->object; ipNetToMediaEntry_type *data; : assume buffer and structure member assignments occur here switch(arg) { case I_atPhysAddress: return o_string(vb, object, data->ipNetToMediaPhysAddress.ptr, data->ipNetToMediaPhysAddress.len); 5–36 eSNMP API Routines...

  • Page 95: O_Counter64

    eSNMP API Routines o_counter64 o_counter64 Loads a counter64 value into the VARBIND structure. Format int o_counter64 ( VARBIND *vb, OBJECT *obj, uint64 value ); (for Alpha) uint64_vax value ; (for VAX)) Arguments A pointer to the VARBIND structure that is supposed to receive the data. A pointer to the OBJECT structure for the MIB variable associated with the OID in the VARBIND structure.

  • Page 96: Str2Oid

    eSNMP API Routines str2oid str2oid Converts a null-terminated string in dot notation to an structure. The str2oid routine does not allocate an structure. Format oid *str2oid ( oid *oid, char *s ); Arguments The value to be inserted as data into the VARBIND structure. For more information about OID length and values, see Chapter 3.

  • Page 97: Sprintoid

    eSNMP API Routines sprintoid sprintoid Converts an into a null-terminated string. Format char *sprintoid ( char *buffer, oid *oid ); Description can have up to 128 elements. A full-sized can require a large buffer. Return Values The return value points to its first argument. Example #include <esnmp.h>...

  • Page 98: Instance2Oid

    eSNMP API Routines instance2oid instance2oid Copies the object’s base OID and appends a copy of the instance array to make a complete OID for a value. This routine does not allocate an OID structure. It only allocates the array containing the elements. Format oid instance2oid ( oid *new, object *obj,...
  • Page 99 eSNMP API Routines instance2oid Example #include <esnmp.h> VARBIND *vb; <-- filled in OBJECT *object; <-- filled in unsigned int instance[6]; -- Construct the outgoing OID in a GETNEXT -- Instance is N.1.A.A.A.A where A’s are IP address -- instance[0] = data->ipNetToMediaIfIndex; instance[1] = 1;...

  • Page 100: Oid2Instance

    eSNMP API Routines oid2instance oid2instance Extracts the instance values from an OID structure and copies them to the specified array of integers. The routine then returns the number of elements in the array. Format int oid2instance ( oid *oid, object *obj, unsigned int *instance, int *max_len );...
  • Page 101 eSNMP API Routines oid2instance Example #include <esnmp.h> *incoming = &method->varbind->name; OBJECT *object = method->object; instLength; unsigned int instance[6]; -- in a GET operation -- -- Expected Instance is N.1.A.A.A.A where A’s are IP address -- instLength = oid2instance(incoming, object, instance, 6); if (instLength != 6) return ESNMP_MTHD_noSuchInstance;...

  • Page 102: Inst2Ip

    eSNMP API Routines inst2ip inst2ip Returns an IP address derived from an OID instance. Format int inst2ip ( unsigned int *instance, int *length, unsigned int *ipaddr, int *exact, int *carry ); Arguments instance A pointer to an array of containing the instance numbers returned unsigned int by the routine to be converted to an IP address.

  • Page 103: Return Values

    eSNMP API Routines inst2ip Description Use the EXACT mode for evaluating an instance for operations. For operations, use the NEXT mode. When using NEXT mode, GetNext GetBulk this routine assumes that the search for data will be performed using greater than or equal to matches.
  • Page 104 eSNMP API Routines inst2ip The search key consists of a number and two ipaddr values. These are represented in the instance part of the OID as n.A.A.A.A.B.B.B.B, where: • n is a single value integer. • The A.A.A.A portion makes up one IP address. •...

  • Page 105: Cmp_Oid

    eSNMP API Routines cmp_oid cmp_oid Compares two OID structures. Format int cmp_oid ( oid *q, oid *p ); Description This routine does an element-by-element comparison, from the most significant element (element 0) to the least significant element. If all other elements are equal, the OID with the least number of elements is considered less.

  • Page 106: Cmp_Oid_Prefix

    eSNMP API Routines cmp_oid_prefix cmp_oid_prefix Compares an OID against a prefix. Format int cmp_oid_prefix ( oid *q, oid *prefix ); Description A prefix could be the OID on an object in the object table. The elements beyond the prefix are the instance information. This routine does an element-by-element comparison, from the most significant element (element 0) to the least significant element.

  • Page 107: Clone_Oid

    eSNMP API Routines clone_oid clone_oid Makes a copy of the OID. This routine does not allocate an OID structure. Format oid clone_oid ( oid *new, oid *oid ); Arguments A pointer to the OID structure that is to receive the copy. A pointer to the OID structure where the data is to be obtained.

  • Page 108: Free_Oid

    eSNMP API Routines free_oid free_oid Frees the OID structure’s buffer. This routine does not deallocate the OID structure itself; it deallocates the elements buffer attached to the structure. Format void free_oid ( oid *oid ); Description This routine frees the buffer pointed to by the OID->elements field and zeros the field and the NELEM structure.

  • Page 109: Clone_Buf

    eSNMP API Routines clone_buf clone_buf Duplicates a buffer in a dynamically allocated space. Format char clone_buf ( char *str, int *len ); Arguments A pointer to the buffer to be duplicated. The number of bytes to be copied. Description One extra byte is always allocated at the end and is filled with zeros. If the length is less than zero, the duplicate buffer length is set to zero.

  • Page 110: Mem2Oct

    eSNMP API Routines mem2oct mem2oct Converts a string (a buffer and length) to an structure with the new buffer’s address and length. Format oct *mem2oct ( oct *new, char *buffer, int *len ); Arguments A pointer to the structure receiving the data. buffer Pointer to the buffer to be converted.

  • Page 111: Cmp_Oct

    eSNMP API Routines cmp_oct cmp_oct Compares two octet strings. Format int cmp_oct ( oct *oct1, oct *oct2 ); Arguments oct1 Pointer to the first octet string. oct2 Pointer to the second octet string. Description The two octet strings are compared byte-by-byte to determine the length of the shortest octet string.

  • Page 112: Clone_Oct

    eSNMP API Routines clone_oct clone_oct Makes a copy of the data in an structure. This routine does not allocate an structure; it allocates the buffer pointed to by the structure. Format oct clone_oct ( oct *new, oct *old ); Arguments A pointer to the structure receiving the data.

  • Page 113: Free_Oct

    eSNMP API Routines free_oct free_oct Frees the buffer attached to an structure. This routine does not deallocate structure; it deallocates the buffer to which the structure points. Format void free_oct ( oct *oct ); Description This routine frees the dynamically allocated buffer to which the structure points, and zeros the pointer and length on the structure.

  • Page 114: Free_Varbind_Data

    eSNMP API Routines free_varbind_data free_varbind_data Frees the dynamically allocated fields in the VARBIND structure. However, this routine does not deallocate the VARBIND structure itself; it deallocates the name and data buffers to which the VARBIND structure points. Format void free_varbind_data ( varbind *vb ); Description This routine performs a (vb->name) operation.

  • Page 115: Set_Debug_Level

    eSNMP API Routines set_debug_level set_debug_level Sets the logging level, which dictates what log messages are generated. The program or module calls the routine during program initialization in response to run-time options. Format void set_debug_level ( int stat, unsigned integer null ); Arguments stat The logging level.

  • Page 116: Is_Debug_Level

    eSNMP API Routines is_debug_level is_debug_level Tests the logging level to see whether the specified logging level is set. You can test the logging levels as follows: Level Meaning ERROR Used when a bad error occurs, requiring restart. WARNING Used when a packet cannot be handled; this also implies ERROR.

  • Page 117: Esnmp_Log

    TRACE Puts a message in the log file if trace is active. For more information about configuration options for logging and tracing, refer to the Compaq TCP/IP Services for OpenVMS Management guide. Example #include <esnmp.h> ESNMP_LOG( ERROR, ("Cannot open file %s\n", file));...

  • Page 118: Print_Varbind

    eSNMP API Routines _ _print_varbind _ _print_varbind Displays the VARBIND and its contents. This routine is used for debugging purposes. To use this routine, you must set the debug level to TRACE . Output is sent to the specified file. Format _ _print_varbind ( VARBIND *vb, int indent );...

  • Page 119: Set_Select_Limit

    eSNMP API Routines set_select_limit set_select_limit Sets the eSNMP select error limit. For more information, see Section 6.1. Format set_select_limit ( char *progname ); Arguments progname The subagent name. This argument is valid with DPI versions only. With AgentX, the argument is NULL because subagents do not get names. Return Values ESNMP_MTHD_noError No error was generated.

  • Page 120: Set_Progname

    eSNMP API Routines _ _set_progname _ _set_progname Specifies the program name that will be displayed in log messages. This routine should be called from the main during program initialization. It needs to be called only once. Format _ _set_progname ( char *prog ); Arguments prog The program name as taken from...

  • Page 121: Restore_Progname

    eSNMP API Routines _ _restore_progname _ _restore_progname Restores the program name from the second application of the set. This routine should be called only after the _ _set_progname routine has been called. You can use this to restore the most recent program name only. Format _ _restore_progname ( );...

  • Page 122: Parse_Progname

    eSNMP API Routines _ _parse_progname _ _parse_progname Parses the full file specification to extract only the file name and file extension. Format _ _parse_progname ( file-specification ); Arguments file-specification The full file specification for the subagent. Example #include "esnmp.h" static char Progname[100]; sprintf (Progname, "%s%.8X", __parse_progname(prog), getpid());...

  • Page 123: Esnmp_Cleanup

    eSNMP API Routines esnmp_cleanup esnmp_cleanup Closes open sockets that are used by the subagent for communicating with the master agent. Format esnmp_cleanup ( ); Example #include "esnmp.h" int rc = ESNMP_LIB_OK; rc = esnmp_cleanup(); Return Values ESNMP_LIB_NOTOK There was no socket. ESNMP_LIB_OK Success.

  • Page 125: Troubleshooting Esnmp Problems

    Log files (Section 6.3) For additional information about troubleshooting SNMP problems, see the Compaq TCP/IP Services for OpenVMS Tuning and Troubleshooting guide. 6.1 Modifying the Subagent Error Limit In certain circumstances, some subagent programs might enter a loop where a call repeatedly returns a -1 error value.

  • Page 126: Log Files

    Troubleshooting eSNMP Problems 6.2 Modifying the Subagent Timeout The TCPIP$ESNMP_DEFAULT_TIMEOUT value is from 0 to 60 seconds. (You should use 0 only for testing purposes, such as simulating problems on a heavily loaded host or network.) If the value you specify contains nonnumeric digits or is outside the allowed range, the default value of 3 seconds is used.
  • Page 127 (see Chapter 5 for more information). set_debug_level Because the chess example subagent does not use a default, messages are captured only if you specify tracing. For information about getting trace logs, refer to the Compaq TCP/IP Services for OpenVMS Management guide. Troubleshooting eSNMP Problems 6–3...

  • Page 129: Index

    Index AgentX protocol, 1–2 free_oct support routine, 5–55 API functionality, 1–6 free_oid support routine, 5–50 ASN.1 files, 3–5 free_varbind_data support routine, 5–56 C compiler, 3–1 *_get method routine, 5–20 Chess example Groups tree structure, 3–4 MIB, 2–6 clone_buf support routine, 5–51 clone_oct support routine, 5–54 clone_oid...
  • Page 130 Management information base (MIB), 1–1 _ _restore_progname support routine, 5–63 Master agent, 1–1 RFCs mem2oct support routine, 5–52 1155, 2–7, 3–1, 3–2, 4–6 method routines 1213, 2–5 routine reference, 5–19 to 5–24 1514, 2–1, 2–5 MIB browser, 4–1 1901 - 1908, 1–8 command examples, 4–6 1902, 3–1, 3–2, 4–6 command flags, 4–2...
  • Page 131 Trap sender (cont’d) command parameters, 4–9 running, 4–9 Troubleshooting features, 6–1 Writing subagents compiling, 3–5 creating source files, 3–5 including in startup and shutdown, 3–12 UNIX utilities, 3–7 linking and building, 3–11 object tables, 3–7 using ASN.1, 3–5 using UNIX utilities, 3–7 Index–3...

Table of Contents