Compaq TCP/IP Services for OpenVMS
SNMP Programming and Reference


Previous Contents Index


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

new

A pointer to the OID structure that is to receive the copy.

oid

A pointer to the OID structure where the data is to be obtained.

Description

This routine dynamically allocates the buffer and inserts its pointer into the OID structure received. The caller must explicitly free this buffer.

Point to the OID structure that is to receive the new OID values and call this routine. Any previous value in the new OID structure is freed (using the free_oid routine) and the new values are dynamically allocated and inserted. To preserve an existing OID structure, initialize the new OID structure with zeros.

If the old OID structure is null or contains a null pointer to its element buffer, a new OID of [0.0] is generated.


Return Values

Null An error or the pointer to the OID is returned.

Example


 
#include <esnmp.h> 
OID oid1; 
OID oid2; 
: 
: assume oid1 gets assigned a value 
: 
memset(&oid2, 0, sizeof(OID)); 
if (clone_oid(&oid2, &oid1) == NULL) 
    DPRINTF((WARNING, "It did not work\n")); 
 


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.

Example


 
include <esnmp.h> 
OID oid; 
: 
: assume oid was assigned a value (perhaps with clone_oid() 
: and we are now finished with it. 
: 
free_oid(&oid); 
 


clone_buf

Duplicates a buffer in a dynamically allocated space.

Format

char clone_buf ( char *str,
int *len );


Arguments

str

A pointer to the buffer to be duplicated.

len

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. A buffer pointer is always returned, unless there is a malloc error.

Return Values

Null A malloc error. Otherwise, the pointer to the allocated buffer that contains a copy of the original buffer is returned.

Example


 
#include <esnmp.h> 
char *str = "something nice"; 
char *copy; 
copy = clone_buf(str, strlen(str)); 


mem2oct

Converts a string (a buffer and length) to an oct structure with the new buffer's address and length.

Format

oct *mem2oct ( oct *new,
char *buffer,
int *len );


Arguments

new

A pointer to the oct structure receiving the data.

buffer

Pointer to the buffer to be converted.

len

Length of buffer to be converted.

Description

The mem2oct routine dynamically allocates the buffer and inserts its pointer into the oct structure. The caller must explicitly free this buffer.

This routine does not allocate an oct structure and does not free data previously pointed to in the oct structure before making the assignment.


Return Values

Null An error occurred. Otherwise, the pointer to the oct structure (the first argument) is returned.

Example


 
#include <esnmp.h> 
char buffer; 
int len; 
OCT abc; 
 
...buffer and len are initialized to something... 
 
memset(&abc, 0, sizeof(OCT)); 
if (mem2oct(&abc, buffer, len) == NULL) 
    DPRINTF((WARNING,"It did not work...\n")); 
 


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. If all bytes are equal, the lengths are compared. An octet with a null pointer is considered the same as a zero-length octet.

Return Values

-1 The string pointed to by the first oct is less than the second.
0 The string pointed to by the first oct is equal to the second.
1 The string pointed to by the first oct is greater than the second.

Example


 
#include <esnmp.h> 
OCT abc, efg; 
 
...abc and efg are initialized to something... 
 
if (cmp_oct(&abc, &efg) > 0) 
    DPRINTF((WARNING,"octet abc is larger than efg...\n")); 
 


clone_oct

Makes a copy of the data in an oct structure. This routine does not allocate an oct structure; it allocates the buffer pointed to by the oct structure.

Format

oct clone_oct ( oct *new,
oct *old );


Arguments

new

A pointer to the oct structure receiving the data.

old

A pointer to the oct structure where the data is to be obtained.

Description

The clone_oct routine dynamically allocates the buffer, copies the data, and updates the oct structure with the buffer's address and length. The caller must free this buffer.

The previous value of the buffer on the new oct structure is freed prior to the new buffer being allocated. If you do not want the old value freed, initialize the new oct structure before cloning.


Return Values

Null An error occurred. Otherwise, the pointer to the oct structure (the first argument) is returned.

Example


 
#include <esnmp.h> 
OCT octet1; 
OCT octet2; 
: 
: assume octet1 gets assigned a value 
: 
memset(&octet2, 0, sizeof(OCT)); 
if (clone_oct(&octet2, &octet1) == NULL) 
    DPRINTF((WARNING, "It did not work\n")); 
 


free_oct

Frees the buffer attached to an oct structure. This routine does not deallocate the oct structure; it deallocates the buffer to which the oct structure points.

Format

void free_oct ( oct *oct );


Description

This routine frees the dynamically allocated buffer to which the oct structure points, and zeros the pointer and length on the oct structure. If the oct structure is already null, this routine does nothing.

If the buffer attached to the oct structure is already null, this routine sets the length field of the oct structure to zero.


Example


 
#include <esnmp.h> 
OCT octet; 
: 
: assume octet was assigned a value (perhaps with mem2oct() 
: and we are now finished with it. 
: 
free_oct(&octet); 
 


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 free_oid (vb->name) operation. If indicated by the vb->type field, it then frees the vb->value data using either the free_oct or the free_oid routine.

Example


 
#include <esnmp.h> 
VARBIND *vb; 
 
vb = (VARBIND*)malloc(sizeof(VARBIND)); 
clone_oid(&vb->name,oid); 
clone_oct(&vb->value.oct,data); 
: 
: some processing that uses vb occurs here 
: 
free_varbind_data(vb); 
free(vb); 
 


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. The following values can be set individually or in combination:
Level Meaning
ERROR Used when a bad error occurred; requires a restart.
WARNING Used when a packet cannot be handled; also implies ERROR. This is the default.
TRACE Used when tracing all packets; also implies ERROR and WARNING.

null

This parameter is not used by OpenVMS. It is supplied for compatibility with UNIX.

Description

The logging level will be ERROR, WARNING, or TRACE.

If you specify TRACE, all three types of errors are generated. If you specify ERROR, only error messages are generated. If you specify WARNING, both error and warning messages are generated.

To specify logging levels for the messages in your subagent, use the ESNMP_LOG routine.


Example


#include <esnmp.h> 
 
if (strcmp("-t", argv[1] { 
    set_debug_level(TRACE,NULL); 
} else { 
    set_debug_level(WARNING,NULL); 
} 


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.
TRACE Used when tracing all packets; this also implies ERROR and WARNING.

Format

int is_debug_level ( int type );


Return Values

TRUE The requested level is set and the ESNMP_LOG will generate output, or output will go to the specified destination.
FALSE The logging level is not set.

Example


 
#include <esnmp.h> 
 
if (is_debug_level(TRACE)) 
    dump_packet(); 


ESNMP_LOG

This is an error declaration C macro defined in the ESNMP.H header file. It gathers the information that it can obtain and sends it to the log.

Format

ESNMP_LOG ( level,
format, ... );


Description

The esnmp_log routine is called using the ESNMP_LOG macro, which uses the helper routine esnmp_logs to format part of the text. Do not use these functions without the ESNMP_LOG macro. For example:


 
#define ESNMP_LOG(level, x) if (is_debug_level(level)) { \
         esnmp_log(level, esnmp_logs x, __LINE__, __FILE__);} 

Where:

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)); 


__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 );


Arguments

vb

The pointer to the VARBIND structure to be displayed. If the vb pointer is NULL, no output is generated.

indent

The number of bytes of white space to place before each line of output.

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.
ESNMP_MTHD_genErr An error was generated.

__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 argv[0] , or some other identification for entity-calling logging routines.

Example


#include "esnmp.h" 
__set_progname(argv[0]); 


__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 ( );


Example


#include "esnmp.h" 
__restore_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()); 


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.


Previous Next Contents Index