TimeFilter proposal (plaintext rewrite)

Here's the complete text of the proposal for easier reading:



TimeFilter ::= TEXTUAL-CONVENTION
   STATUS        current
   DESCRIPTION
       "To be used for the index to a table.  Allows an application
       to download only those rows changed since a particular time.
       Note that this is not a history mechanism.  Only current values
       of underlying objects are returned, not saved instance values
       associated with particular values of sysUpTime.

       An entry is considered changed if the value of any object in the
       entry changes, if the row is created, or if any object in the
       entry is created or deleted.  Note that deleted entries cannot be
       detected or downloaded.

       A time-filtered conceptual table is created by inserting a
       single object of SYNTAX TimeFilter as the first INDEX component
       in a copy of an existing basic conceptual table (i.e., any
       SEQUENCE without a TimeFilter INDEX component).  Thus, for
       each conceptual entry 'I' in the basic table, there exists N
       conceptual entries in the time-filtered version, (indexed N.I)
       where 'N' is equal to the value of sysUpTime.

       When an application retrieves conceptual instances from a
       time-filtered table, and an INDEX value is provided for the
       TimeFilter INDEX component 'N', the agent will only consider
       returning basic conceptual entries (e.g., 'fooColumn.N.I') if
       any column within the basic conceptual entry has changed since
       sysUpTime equals 'N'.  If not, the basic conceptual entry will
       be ignored for the particular retrieval operation.

       When sysUpTime is equal to zero, this table shall be empty.

       One conceptual entry exists for each past value of sysUpTime, except
       that the whole table is purged should sysUpTime wrap.

       As an entry in a time-filtered table is updated (i.e., one of
       the columns in the basic conceptual table is changed), new 
conceptual
       entries are also created in the time-filtered version 
(which still share
       the now updated object values with all other instances).  The number
       of unique time-filtered instances which are created is 
determined by the value of
       sysUpTime at which the basic entry was last updated.  One unique 
instance
       will exist for each value of sysUpTime at the last update time 
for the
       row.  However, a new TimeFilter index instance is created for 
each new
       sysUpTime value.  The TimeFilter index values not associated 
with entry
       updates are called duplicate time-filtered instances.

       See the appendix for further discussion of this textual convention.

       Consider the following basic conceptual table basicFooTable
       (Note that the basic version of a time-filtered table may not
       actually be defined.

           basicFooTable:

           basicFooTable ...
           INDEX { fooIndex }

           BasicFooEntry {
              fooIndex     Integer32,
              fooCounts    Counter32
           }

       For this example, the basicFooTable contains two static conceptual
       entries (fooIndex equals '1' and '2'), created at time zero.
       It also contains one dynamic conceptual entry (fooIndex equals '3'),
       which is created at time '3' and deleted at time '7'.

      The time-filtered version of the basicFooTable could be defined 
as follows:

           FooTable:

           fooTable ...
           INDEX { fooTimeMark, fooIndex }

           FooEntry {
              fooTimeMark  TimeFilter,               
              fooIndex     Integer32,
              fooCounts    Counter32
           }


       Note that entries exist in the time-filtered conceptual table
       only if they actually exist in the underlying (basic) table.

       For this example, the fooTable will have three underlying
       basic entries (fooIndex == 1, 2, and 3), with the following
       activity (for sysUpTime equal 0 to 9):
 
          - fooEntry.N.1 is created at time '0', and most recently
            updated at time '6' to the value '5'.
          - fooEntry.N.2 is created at time '0', and most recently
            updated at time '8' to the value '9'.
          - fooEntry.N.3 is created at time '3', and most recently
            updated at time '5' to the value '17'.

      The following tables show the values that would be returned for
      'MIB walk' operations with various TimeFilter values, done 
at different
      times.  An application issues a retrieval request at time 'T',
      with a TimeFilter value 'N' (typically set to a lower value, such as
      the value of sysUpTime at the last polling cycle).

      The following values would be returned in a MIB walk of fooCounts.N
      if T equals '0' and N equals '0':

            fooCounts.N.I    Value
            ==========================
            fooCounts.0.1    0
            fooCounts.0.2    0
              
        Note there is nothing returned for fooCounts.0.3 since that entry
        does not exist at sysUpTime equals '0'.

      The following values would be returned in a full (traditional) 
MIB walk
      of fooCounts.N if T equals '3' and N equals '0':

            fooCounts.N.I    Value
            =======================
            fooCounts.0.1    0
            fooCounts.0.2    0
            fooCounts.0.3    0
            fooCounts.1.3    0
            fooCounts.2.3    0
            fooCounts.3.3    0
              
        Note that there are no instances for T equals 1 or 2, for the
        first two values of N, since these entries did not change
        since they were created at time '0'.

        Note that the current value for 'fooCounts.N.3' is returned 
here, even
        for values of N less than '3' (when the entry was created).  The
        agent only considers the current existence of an entry in the
        TimeFilter algorithm, not the time when the entry was created.

        Note that the instances 'fooCounts.0.3', 'fooCounts.1.3'
        and 'fooCounts.2.3' are duplicates and can be suppressed by the
        agent in a MIB walk.

      The following values would be returned in a full (traditional) 
MIB walk
      of fooCounts.N if T equals '6' and N equals '3':

            fooCounts.N.I    Value
            =======================
            fooCounts.3.1    5
            fooCounts.3.3    17
            fooCounts.4.1    5
            fooCounts.4.3    17
            fooCounts.5.1    5
            fooCounts.5.3    17
            fooCounts.6.1    5

         Note that no instances for entry 'fooCounts.N.2' are returned 
since
         it has not changed since time '3'.

         Note that all instances except 'fooCounts.5.3' and 'fooCounts.6.1'
         are duplicates and can be suppressed by the agent in a MIB walk.

      The following values would be returned in a full (traditional) 
MIB walk
      of fooCounts.N if T equals '9' and N equals '6':

            fooCounts.N.I    Value
            =======================
            fooCounts.6.1    5
            fooCounts.6.2    9
            fooCounts.7.2    9
            fooCounts.8.2    9
    
         Note that no instances for entry 'fooCounts.N.3' are returned 
since
         it has not changed since time '5'.

         Note that instances 'fooCounts.6.2' and 'fooCounts.7.2'
         are duplicates and can be suppressed by the agent in a MIB walk.
   
    After some deployment experience, it has been determined that
    a time-filtered table is more efficient to use if the agent
    stops a 'MIB walk' operation by skipping over rows with a
    TimeFilter index value higher than the value in the received
    GetNext/GetBulk request. That is, instead of incrementing a
    TimeFilter index value, the agent will continue to the next
    object or table. As a consequence, GetNext or GetBulk
    operations will provide only one pass through a time-filtered
    table.

    It is suggested for an agent to implement a time-filtered
    table in this manner to improve performance and avoid a 'MIB walk'
    getting stuck in time-filtered tables. It is, however, still acceptable
    for an agent to implement a time-filtered table the traditional
    manner (i.e., every conceptual time-filtered instance is
    returned in GetNext and GetBulk PDU responses) and management
    applications must be able to deal with such traditional
    implementations."
   SYNTAX    TimeTicks