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.
4.
Each row is released. The same single method routine for each row is called
with a method->action equal to ESNMP_ACT_CLEANUP. This occurs for
every row, regardless of the results of previous processing.
The action codes are processed as follows:
•
ESNMP_ACT_SET
Each object’s method routine is called during the SET phase, until all objects
are processed or a method routine returns an error status value. (This is the
only phase during which each object’s method routine is called.) For variable
bindings in the same conceptual row, method->row points to a common ROW_
CONTEXT.
The method->flags bitmask has the ESNMP_LAST_IN_ROW bit set, if this is
the last object being called for this ROW_CONTEXT. This enables you to do a
final consistency check, because you have seen every variable binding for this
conceptual row.
The method routine’s job in this phase is to determine whether the
Set
request will work, to return the correct SNMP error code if it does not, and to
prepare any context data it needs to actually perform the
Set
request during
the COMMIT phase.
The method->row->context field is private to the method routine;
libesnmp
does not use it. A typical use is to store the address of an emitted structure
that has been loaded with the data from the VARBIND for the conceptual
row.
•
ESNMP_ACT_COMMIT
Even though several variable bindings may be in a conceptual row, only the
last one in order of the
Set
request is processed. Of all the method routines
that point to a common row, only the last method routine is called.
This method routine must have available to it all necessary data and
context to perform the operation. It must also save a snapshot of current
data or whatever it needs to undo the
Set
operation, if required. The
method->row->save field is intended to hold a pointer to whatever data is
needed to accomplish this. A typical use is to store the address of a structure
that has been loaded with the current data for the conceptual row. The
structure is one that has been automatically generated by the MIBCOMP
command.
The method->row->save field is also private to the method routine;
libesnmp
does not use it.
If this operation succeeds, return
ESNMP_MTHD_noError
; otherwise, return a
value of
ESNMP_MTHD_commitFailed
.
If any errors were returned during the COMMIT phase,
libesnmp
enters the
UNDO phase; if not, it enters the CLEANUP phase.
Note
If the
Set
request spans multiple subagents and another subagent fails,
the UNDO phase may occur even if the
Set
operation is successful
eSNMP API Routines 5–25
