[Ericsson AB]

11 Definition of Instrumentation Functions

The section Definition of Instrumentation Functions describes the user defined functions, which the agent calls at different times.

11.1 Variable Instrumentation

For scalar variables, a function f(Operation, ...) must be defined.

The Operation can be new, delete, get, is_set_ok, set, or undo.

In case of an error, all instrumentation functions may return either an SNMPv1 or an SNMPv2 error code. If it returns an SNMPv2 code, it is converted into an SNMPv1 code before it is sent to a SNMPv1 manager. It is recommended to use the SNMPv2 error codes for all instrumentation functions, as these provide more details. See Appendix A for a description of error code conversions.

11.1.1 f(new [, ExtraArgs])

The function f(new [, ExtraArgs]) is called for each variable in the MIB when the MIB is loaded into the agent. This makes it possible to perform necessary initialization.

This function is optional. The return value is discarded.

11.1.2 f(delete [, ExtraArgs])

The function f(delete [, ExtraArgs]) is called for each object in an MIB when the MIB is unloaded from the agent. This makes it possible to perform necessary clean-up.

This function is optional. The return value is discarded.

11.1.3 f(get [, ExtraArgs])

The function f(get [, ExtraArgs]) is called when a get-request or a get-next request refers to the variable.

This function is mandatory.

11.1.3.1 Valid Return Values

11.1.4 f(is_set_ok, NewValue [, ExtraArgs])

The function f(is_set_ok, NewValue [, ExtraArgs]) is called in phase one of the set-request processing so that the new value can be checked for inconsistencies.

NewValue is guaranteed to be of the correct type, length and within ranges, as specified in the MIB. If the object is an enumerated integer or of type BITS, the integer value is used.

This function is optional.

If this function is called, it will be called again, either with undo or with set as first argument.

11.1.4.1 Valid return values

11.1.5 f(undo, NewValue [, ExtraArgs])

If an error occurred, this function is called after the is_set_ok function is called. If set is called for this object, undo is not called.

NewValue is guaranteed to be of the correct type, length and within ranges, as specified in the MIB. If the object is an enumerated integer or of type BITS, the integer value is used.

This function is optional.

11.1.5.1 Valid return values

11.1.6 f(set, NewValue [, ExtraArgs])

This function is called to perform the set in phase two of the set-request processing. It is only called if the corresponding is_set_ok function is present and returns noError.

NewValue is guaranteed to be of the correct type, length and within ranges, as specified in the MIB. If the object is an enumerated integer or of type BITS, the integer value is used.

This function is mandatory.

11.1.6.1 Valid return values

11.2 Table Instrumentation

For tables, a f(Operation, ...) function should be defined (the function shown is exemplified with f).

The Operation can be new, delete, get, next, is_set_ok, undo or set.

In case of an error, all instrumentation functions may return either an SNMPv1 or an SNMPv2 error code. If it returns an SNMPv2 code, it is converted into an SNMPv1 code before it is sent to a SNMPv1 manager. It is recommended to use the SNMPv2 error codes for all instrumentation functions, as these provide more details. See Appendix A for a description of error code conversions.

11.2.1 f(new [, ExtraArgs])

The function f(new [, ExtraArgs]) is called for each object in an MIB when the MIB is loaded into the agent. This makes it possible to perform the necessary initialization.

This function is optional. The return value is discarded.

11.2.2 f(delete [, ExtraArgs])

The function f(delete [, ExtraArgs]) is called for each object in an MIB when the MIB is unloaded from the agent. This makes it possible to perform any necessary clean-up.

This function is optional. The return value is discarded.

11.2.3 f(get, RowIndex, Cols [, ExtraArgs])

The function f(get, RowIndex, Cols [, ExtraArgs]) is called when a get-request refers to a table.

This function is mandatory.

11.2.3.1 Arguments

11.2.3.2 Valid Return Values

11.2.4 f(get_next, RowIndex, Cols [, ExtraArgs])

The fumction f(get_next, RowIndex, Cols [, ExtraArgs]) is called when a get-next- or a get-bulk-request refers to the table.

The RowIndex argument may refer to an existing row or a non-existing row, or it may be unspecified. The Cols list may refer to unaccessible columns or non-existing columns. For each column in the Cols list, the corresponding next instance is determined, and the last part of its OBJECT IDENTIFIER and its value is returned.

This function is mandatory.

11.2.4.1 Arguments

11.2.4.2 Valid Return Values

11.2.5 f(is_set_ok, RowIndex, Cols [, ExtraArgs])

The fumction f(is_set_ok, RowIndex, Cols [, ExtraArgs]) is called in phase one of the set-request processing so that new values can be checked for inconsistencies.

If the function is called, it will be called again with undo, or with set as first argument.

This function is optional.

11.2.5.1 Arguments

11.2.5.2 Valid Return Values

11.2.6 f(undo, RowIndex, Cols [, ExtraArgs])

If an error occurs, The fumction f(undo, RowIndex, Cols [, ExtraArgs]) is called after the is_set_ok function. If set is called for this object, undo is not called.

This function is optional.

11.2.6.1 Arguments

11.2.6.2 Valid Return Values

11.2.7 f(set, RowIndex, Cols [, ExtraArgs])

The fumction f(set, RowIndex, Cols [, ExtraArgs]) is called to perform the set in phase two of the set-request processing. It is only called if the corresponding is_set_ok function did not exist, or returned {noError, 0}.

This functionn is mandatory.

11.2.7.1 Arguments

11.2.7.2 Valid Return Values


Copyright © 1991-2006 Ericsson AB