Containers

Some (incomplete) ramblings about netsnmp_containers...

Inroduction

Containers are a generic data interface, similar to a database. Like a database, you use an index (aka key) to access and sort the data. Containers use a compare function provided by the user to determine the sort order. The function is called with a pointer to two data itmes, and must return a value indicating which of the two has the lesser index value. So, by providing a second compare function allows the user to access the data in a different order.

SNMP tables have indexes. A table index may have multiple components which, taken together, uniquely identify a row.

Now, when the two are used together, it easy to get confused. All of the MIB indexes, taken together, are the primary container index. Even if a MIB table has a dozen indexes, the container only has one.

To clarify futher, here's an example. Let's say we are creating a SNMP interface to a hotel reservation system. The (simplified) table looks like this:

guestTable

 guestEntry INDEX { building, room }
   building INTEGER
   room     INTEGER
   name     STRING

So, the MIB has two indexes, the building and room numbers. The primary MIB index is the building, and the secondary MIB index is the room. However, the primary index of the container will be the combined index OIDs (building.room).

Comparison routines

The default compare routine for containers assumes that the data record's first component is a netsnmp_index, so when using an OID as a key, you don't need to provide a comparison routine. If you wanted to provide your own compare routine, it might look something like this:

 int
 netsnmp_compare_netsnmp_index(guestTable *lh_guest, guestTable *rh_guests)
 {
   /* compare building, then room */
   if(lh_guest->building == rh_guest->building) {
       if(lh_guest->room == rh_guest->room)
          return 0;
       else {
          if(lh_guest->room < rh_guest->room)
             return -1;
          else
             return 1;
       }
   }
   else {
      if(lh_guest->building < rh_guest->building)
        return -1;
      else
        return 1;
   }
 }

So we now have a container with the guest data, and we can look up data by building and room number. What if our application now needs to generate a guest report, but sorted by name? We have the data, but in the wrong sort order. This is where you would use a secondary index to the container. The new compare might look like this:

 int
 netsnmp_compare_netsnmp_index(guestTable *lh_guest, guestTable *rh_guests)
 {
    /* compare name, then building and room */
    int rc = strcmp(lh_guest->name,rh_guest->name);
    if(rc != 0)
       return rc;

    if(lh_guest->building == rh_guest->building) {
       if(lh_guest->room == rh_guest->room)
            return 0;
       else {
          if(lh_guest->room < rh_guest->room)
             return -1;
          else
             return 1;
       }
    }
    else {
       if(lh_guest->building < rh_guest->building)
          return -1;
       else
          return 1;
    }
 }