From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/snmp/doc/src/snmp_def_instr_functions.xml | 477 ++++++++++++++++++++++++++ 1 file changed, 477 insertions(+) create mode 100644 lib/snmp/doc/src/snmp_def_instr_functions.xml (limited to 'lib/snmp/doc/src/snmp_def_instr_functions.xml') diff --git a/lib/snmp/doc/src/snmp_def_instr_functions.xml b/lib/snmp/doc/src/snmp_def_instr_functions.xml new file mode 100644 index 0000000000..f88469aeae --- /dev/null +++ b/lib/snmp/doc/src/snmp_def_instr_functions.xml @@ -0,0 +1,477 @@ + + + + +
+ + 19972009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Definition of Instrumentation Functions + + + + + + + + snmp_def_instr_functions.xml +
+

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

+ +
+ 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. +

+ +
+ 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.

+
+ +
+ 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.

+
+ +
+ 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. +

+ +
+ Valid Return Values + + {value, Value}. The Value must be of + correct type, length and within ranges, otherwise + genErr is returned in the response PDU. If the + object is an enumerated integer, the symbolic enum value + may be used as an atom. If the object is of type BITS, the + return value shall be an integer or a list of bits that + are set. + + {noValue, noSuchName}(SNMPv1) + + {noValue, noSuchObject | noSuchInstance} (SNMPv2) + + genErr. Used if an error occurred. Note, + this should be an internal processing error, e.g. a caused + by a programing fault somewhere. If the variable does not + exist, use {noValue, noSuchName} or + {noValue, noSuchInstance}. + + +
+
+ +
+ 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. +

+ +
+ Valid return values + + noError + badValue | noSuchName | genErr(SNMPv1) + + noAccess | noCreation | inconsistentValue | resourceUnavailable | inconsistentName | genErr(SNMPv2) + +
+
+ +
+ 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. +

+ +
+ Valid return values + + noError + genErr(SNMPv1) + + undoFailed | genErr(SNMPv2) + +
+
+ +
+ 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. +

+ +
+ Valid return values + + noError + genErr(SNMPv1) + + commitFailed | undoFailed | genErr(SNMPv2) + +
+
+
+ +
+ 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.

+ +
+ 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.

+
+ +
+ 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.

+
+ +
+ 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. +

+ +
+ Arguments + + RowIndex is a list of integers which define the + key values for the row. The RowIndex is the list + representation (list of integers) which follow the + Cols integer in the OBJECT IDENTIFIER. + + Cols is a list of integers which represent the + column numbers. The Cols are sorted by increasing + value and are guaranteed to be valid column numbers. + +
+ +
+ Valid Return Values + + +

A list with as many elements as the Cols list, + where each element is the value of the corresponding + column. Each element can be:

+ + {value, Value}. The Value must be of + correct type, length and within ranges, otherwise + genErr is returned in the response PDU. If the + object is an enumerated integer, the symbolic enum + value may be used (as an atom). If the object is of + type BITS, the return value shall be an integer or a + list of bits that are set. + + {noValue, noSuchName}(SNMPv1) + + {noValue, noSuchObject | noSuchInstance}(SNMPv2) + + + + {noValue, Error}. If the row does not exist, + because all columns have {noValue, Error}), the + single tuple {noValue, Error} can be returned. + This is a shorthand for a list with all elements + {noValue, Error}. + + genErr. Used if an error occurred. Note that + this should be an internal processing error, e.g. a caused + by a programing fault somewhere. If some column does not + exist, use {noValue, noSuchName} or + {noValue, noSuchInstance}. + + +
+
+ +
+ f(get_next, RowIndex, Cols [, ExtraArgs]) +

The function 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 inaccessible 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. +

+ +
+ Arguments + + RowIndex is a list of integers (possibly empty) + that defines the key values for a row. The RowIndex + is the list representation (list of integers), which follow + the Cols integer in the OBJECT IDENTIFIER. + + Cols is a list of integers, greater than or + equal to zero, which represents the column numbers. + +
+ +
+ Valid Return Values + + +

A list with as many elements as the Cols list + Each element can be:

+ + {NextOid, NextValue}, where NextOid + is the lexicographic next OBJECT IDENTIFIER for the + corresponding column. This should be specified as the + OBJECT IDENTIFER part following the table entry. This + means that the first integer is the column number and + the rest is a specification of the keys. + NextValue is the value of this element. + + endOfTable if there are no accessible + elements after this one. + + + + {genErr, Column} where Column denotes + the column that caused the error. Column must be + one of the columns in the Cols list. Note that + this should be an internal processing error, e.g. a caused + by a programing fault somewhere. If some column does not + exist, you must return the next accessible element (or + endOfTable). + + +
+
+ +
+ f(is_set_ok, RowIndex, Cols [, ExtraArgs]) +

The function 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. +

+ +
+ Arguments + + RowIndex is a list of integers which define the + key values for the row. The RowIndex is the list + representation (list of integers) which follow the + Cols integer in the OBJECT IDENTIFIER. + + Cols is a list of {Column, NewValue}, + where Column is an integer, and 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. The list is sorted by Column (increasing) and + each Column is guaranteed to be a valid column + number. + +
+ +
+ Valid Return Values + + {noError, 0} + {Error, Column}, where Error is the same + as for is_set_ok for variables, and Column + denotes the faulty column. Column must be one of the + columns in the Cols list. + +
+
+ +
+ f(undo, RowIndex, Cols [, ExtraArgs]) +

If an error occurs, The function + 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. +

+ +
+ Arguments + + RowIndex is a list of integers which define the + key values for the row. The RowIndex is the list + representation (list of integers) which follow the + Cols integer in the OBJECT IDENTIFIER. + + Cols is a list of {Column, NewValue}, + where Column is an integer, and 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. The list is sorted by Column (increasing) and + each Column is guaranteed to be a valid column + number. + + +
+ +
+ Valid Return Values + + {noError, 0} + {Error, Column} where Error is the same + as for undo for variables, and Column denotes + the faulty column. Column must be one of the columns + in the Cols list. + + +
+
+ +
+ f(set, RowIndex, Cols [, ExtraArgs]) +

The function 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 function is mandatory. +

+ +
+ Arguments + + RowIndex is a list of integers that define the + key values for the row. The RowIndex is the list + representation (list of integers) which follow the + Cols integer in the OBJECT IDENTIFIER. + + Cols is a list of {Column, NewValue}, + where Column is an integer, and 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. The list is sorted by Column (increasing) and + each Column is guaranteed to be a valid column + number. + + +
+ +
+ Valid Return Values + + {noError, 0} + {Error, Column} where Error is the same + as set for variables, and Column denotes + the faulty column. Column must be one of the columns + in the Cols list. + +
+
+
+ + -- cgit v1.2.3