|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
Makes a copy of the OID. This routine does not allocate an OID structure.
oid clone_oid ( oid *new,
oid *oid );
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.
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.
Null An error or the pointer to the OID is returned.
#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"));
Frees the OID structure's buffer. This routine does not deallocate the OID structure itself; it deallocates the elements buffer attached to the structure.
void free_oid ( oid *oid );
This routine frees the buffer pointed to by the OID->elements field and zeros the field and the NELEM structure.
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);
Duplicates a buffer in a dynamically allocated space.
char clone_buf ( char *str,
int *len );
str
A pointer to the buffer to be duplicated.len
The number of bytes to be copied.
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.
Null A malloc error. Otherwise, the pointer to the allocated buffer that contains a copy of the original buffer is returned.
#include <esnmp.h> char *str = "something nice"; char *copy; copy = clone_buf(str, strlen(str));
Converts a string (a buffer and length) to an oct structure with the new buffer's address and length.
oct *mem2oct ( oct *new,
char *buffer,
int *len );
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.
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.
Null An error occurred. Otherwise, the pointer to the oct structure (the first argument) is returned.
#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"));
Compares two octet strings.
int cmp_oct ( oct *oct1,
oct *oct2 );
oct1
Pointer to the first octet string.oct2
Pointer to the second octet string.
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.
-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.
#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"));
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.
oct clone_oct ( oct *new,
oct *old );
new
A pointer to the oct structure receiving the data.old
A pointer to the oct structure where the data is to be obtained.
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.
Null An error occurred. Otherwise, the pointer to the oct structure (the first argument) is returned.
#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"));
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.
void free_oct ( oct *oct );
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.
#include <esnmp.h> OCT octet; : : assume octet was assigned a value (perhaps with mem2oct() : and we are now finished with it. : free_oct(&octet);
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.
void free_varbind_data ( varbind *vb );
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.
#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);
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.
void set_debug_level ( int stat,
unsigned integer null );
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.
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.
#include <esnmp.h> if (strcmp("-t", argv[1] { set_debug_level(TRACE,NULL); } else { set_debug_level(WARNING,NULL); }
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.
int is_debug_level ( int type );
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.
#include <esnmp.h> if (is_debug_level(TRACE)) dump_packet();
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.
ESNMP_LOG ( level,
format, ... );
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:
- x is a text string; for example, a printf statement.
- level is one of the following:
ERROR Declares an error condition. WARNING Declares a warning. 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 HP TCP/IP Services for OpenVMS Management guide.
#include <esnmp.h> ESNMP_LOG( ERROR, ("Cannot open file %s\n", file));
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.
__print_varbind ( VARBIND *vb,
int indent );
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.
Sets the eSNMP select error limit. For more information, see Section 6.1.
set_select_limit ( char *progname );
progname
The subagent name. This argument is valid with DPI versions only. With AgentX, the argument is NULL because subagents do not get names.
ESNMP_MTHD_noError No error was generated. ESNMP_MTHD_genErr An error was generated.
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.
__set_progname ( char *prog );
prog
The program name as taken from argv[0] , or some other identification for entity-calling logging routines.
#include "esnmp.h" __set_progname(argv[0]);
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.
__restore_progname ( );
#include "esnmp.h" __restore_progname();
Parses the full file specification to extract only the file name and file extension.
__parse_progname ( file-specification );
file-specification
The full file specification for the subagent.
#include "esnmp.h" static char Progname[100]; sprintf (Progname, "%s%.8X", __parse_progname(prog), getpid());
Closes open sockets that are used by the subagent for communicating with the master agent.
esnmp_cleanup ( );
#include "esnmp.h" int rc = ESNMP_LIB_OK; rc = esnmp_cleanup();
ESNMP_LIB_NOTOK There was no socket. ESNMP_LIB_OK Success.
| Previous | Next | Contents | Index |