class ref name: dbag
category-group: dbag
layer: 3

synopsis.
The databag object (dbag_o) represents the top class in a class hierarchy of databags: simple databag; list databag; array databag; etc. The dbag_o class is abstract (eg, pure virtual); hence, a (dbag_o) in itself cannot be created. The following functions are pure virtual:

  dbag_o *clone () const
  const string_o &get (count_t, int * = NULL) const;
  const string_o &get (const string_o &, int * = NULL) const;
  boolean contains (const dbag_o &) const;
  const string_o &iprint (string_o &, const count_t) const;

The class provides an interface for all types of databags. This means that every databagt class, which is subtyped from the dbag_o class, must implement the virtual functions of this class. Ocassionally the operation does not make sense, in which case the operation returns a "failure" code, either as -1 for the [integer] return code, or via the final int * output parameter (in the case where a reference to an object is returned). However, most functions have meaning in all sub-types: get(), get_dbag(), put(), put_dbag(), size(), and so on.

member functions (primary)

dbag_o()
SIGNATURE: dbag_o ()
SYNOPSIS:
creates a a new dbag object, completely devoid of contents. The object has no internal structure - no string has been given to it to define any data structure. This "function" cannot be called directly, since this class is abstract (this is called only via instantiation of sub-classes).
 

dbag_o(dbag_o)
SIGNATURE: dbag_o (const dbag_o &that)
SYNOPSIS:
copy constructor: creates a a new databag object which is an exact image of the copied databag object "that". This constructor ["function"] cannot be called directly, since this class is abstract (this is called only via instantiation of sub-classes).
 

operator = (dbag_o)
SIGNATURE: const dbag_o &operator = (const dbag_o &rhs)
SYNOPSIS:
copies exactly the RHS object ("rhs"), to the existing databag object instance.
Note that although this operation can be explicitly done, doing so is strange. This operator is intended to be called only via sub-classes.
RETURNS: a reference to the current databag object
 

destructor
SIGNATURE: ~dbag_o ()
SYNOPSIS:
virtual destructor. The databag instance is wiped out and all contents are reinitialized to the at-construction state. This is [almost?] always called exclusively as part of the destruction process of a sub-class instance.
TRAITS: this function is virtual (as usual)
 

dbag_o(<args>)
SIGNATURE: dbag_o (const string_o &s)
SYNOPSIS:
create a new databag object. This constructor does nothing more than set the name of the databag, to that of the parameter, "s". This constructor cannot be called directly, but only through the construction process of subclasses.
PARAMETERS

s: the name to be assigned to the databag. the contents of 's' should be a simple "name" - characters consisting of letters and or numbers (and possibly embedded underscores - '_').

 

dbag_name()
SIGNATURE: const string_o &dbag_name (int *pi = NULL) const
SYNOPSIS:
returns the name of the databag. Every databag has a name - this is the top-level string. The name of the databag is generally used as a component in a search string, just like a directory in a file system.
 

dbag_type()
SIGNATURE: const string_o &dbag_type (int *pi = NULL) const
SYNOPSIS:
returns the type of the current databag object (as a string_o). This is useful for downcasting, which is a common thing to do with databags. If you are pulling databags out of a recursive databag, and you want to do a recursive descent, you will need to determine the type of the each databag. If it is a recursive databag, you would then need to downcast and descend:

void descend (string_o path)
{
    int ie;
    path += " " + my_bag.dbag_name();
    dbag_o &my_bag = get_dbag(0, &ie);
    if (!ie)
    {
        if (my_bag.dbag_type(&ie) == DBAG_CLASSTYPE_RECURSE)
        {
            descend(path);
        }
        else if (my_bag.dbag_type(&ie) == DBAG_CLASSTYPE_SIMPLE)
        {
            std::cout << "DATABAG LEAF NODE: " << path << "\n";
        }
    }
}

This example is a watered-down sliver of a recursive descent. In a real-world case you would probably iterate through every sub-array in a recursive databag instance, and handle other types of databags (matrix, list, array, etc).
 

operator == (dbag_o)
SIGNATURE: int operator == (const dbag_o &that) const
SYNOPSIS: tells if the current databag has the same name as the RHS object 'that'.
DESCRIPTION: this is not meant to be called literally - directly! this is a placeholder for databag subclasses
 

operator != (dbag_o)
SIGNATURE: int operator != (const dbag_o &that) const
SYNOPSIS: tells if the current databag has a different name from the RHS object 'that'.
DESCRIPTION: this is not meant to be called literally - directly! this is a placeholder for databag subclasses
 

size()
SIGNATURE: count_t size () const
SYNOPSIS:
this is a virtual function that tells how many elements are contained in the [current] databag object. for this class ( dbag_o ), this value is always 0 since this top-level class, dbag_o, is provided as an interface only and cannot hold anything itself.
RETURNS: 0
 

is_ok()
SIGNATURE: boolean is_ok () const
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

is_modified()
SIGNATURE: boolean is_modified () const
SYNOPSIS:
this returns TRUE if the databag has been modified after its construction. If the databag has not changed since its creation, this returns FALSE.
This function behaves exactly the same for every subclass. Important Note: if a databag has been modified, it does not notify any parent-containing databag.
RETURNS:
TRUE: databag has been modified.
FALSE: databag's contents has not been altered since its creation.
 

is_loaded()
SIGNATURE: boolean is_loaded () const
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

is_announcing_errors()
SIGNATURE: boolean is_announcing_errors() const
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

num_chars()
SIGNATURE: count_t num_chars () const
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

nchars_indent()
SIGNATURE: count_t nchars_indent () const
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

isset_mod_oncopy()
SIGNATURE: boolean isset_mod_oncopy (int *pi = NULL)
SYNOPSIS: returns TRUE if the global flag 'gmod_oncopy' is set.
TRAITS: this is a static member function; do not call it with an object instance.
 

isset_deepmod()
SIGNATURE: boolean isset_deepmod (int *pi = NULL)
SYNOPSIS:
returns TRUE if the global flag 'gmod_oncopy' is set. this member function is purely an alias for isset_mod_oncopy().
TRAITS: this is a static member function; do not call it with an object instance.
 

set_dbag_name()
SIGNATURE: int set_dbag_name (const string_o &)
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

set_dbag_type()
SIGNATURE: int set_dbag_type (const string_o &)
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

set_nchars_indent()
SIGNATURE: int set_nchars_indent (count_t)
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

set_modified()
SIGNATURE: int set_modified ()
SYNOPSIS:
this designates the object as having been modified. This function is called automatically by all functions that add or update data to a databag, such as put(), put_dbag(), add_dbag(), or merge_dbag().
 

set_unmodified()
SIGNATURE: int set_unmodified ()
SYNOPSIS:
this is the inverse function of 'set_modified()'. It marks the object as having not been modified. It is used by the orthodox_o and dbbi_o classes, such as when an object is retrieved from a database, to denote that the contents has not yet been modified by the application.
 

mod_setall()
SIGNATURE: int mod_setall (boolean ison = TRUE)
SYNOPSIS:
this function is like set_modified(), but only in that it turns the "is-modified" flag on. This is a virtual function, and it is redefined in other databag classes such as list or matrix databags. In those variations, it will turn on the "is-modified" flag for all databags contained within the object. In the case of this class specifically (dbag_o), this function simply calls set_modified(). This is the default behaviour for a databag class and is used by databag classes that contain no sub-databags internally (eg, "array" and "simple").
TRAITS: this function is virtual.
 

mod_clearall()
SIGNATURE: int mod_clearall ()
SYNOPSIS:
this function is the converse of mod_setall(). It turns off the "is-modified" property for the current object and all sub-databags inside the current object.
DESCRIPTION:
this function actually calls mod_setall() and is simply an alias for mod_setall(FALSE). See mod_setall() or the main discussion page of the databag group for more information on the behaviours of these functions.
TRAITS: this function is inline.
 

announce_errors()
SIGNATURE: int announce_errors (boolean = TRUE)
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

dont_announce_errors()
SIGNATURE: int dont_announce_errors ()
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

reset()
SIGNATURE: int reset ()
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

empty_out()
SIGNATURE: int empty_out ()
SYNOPSIS:
"empties out" the current object. The intent of this function, common to all databag sub-types, is to delete all internal data, but preserve the object's structure, such as the name of the object.
DESCRIPTION:
This member function "empties out" all data from the object. For this class, since there is no data, it in effect does nothing.
 

clone()
SIGNATURE: dbag_o *clone () const
SYNOPSIS:
This will make a complete copy of the current object. This is a pure virtual function, so it must be implemented in subclasses. The operation will be forwarded to the subclass, which will handle the details of copying itself. The newly created object instance will, of course, be of the same type. The returned handle to the object is upcasted to the base class dbag_o.
 

get()
SIGNATURE: const string_o &get (count_t idx, int *pi = NULL) const = 0
SYNOPSIS:
This special member function cannot be called directly. Since it is a pure virtual function, it is one of the few functions that prevent the (dbag_o) class from being instantiated. The purpose of this function is to find the 'nth' element (eg element number indexed by the value of 'idx'] of a databag. The meaning of "nth element" is left up to the subclass.
If the subclass cannot decide on a suitable interpretation of the meaning of "nth element", its implemtation of this routine should set 'pi' to non-zero and the return value to string_o::bad_reference().
TRAITS: PURE VIRTUAL FUNCTION.
 

get()
SIGNATURE: const string_o &get (const string_o &s, int *pi = NULL) const = 0
SYNOPSIS:
this is another version of get(), with a different signiture but related to get(count_t). It is also a pure virtual function, thus precluding this class from being instantiated. The objective of this function is to return the "element" of the given databag that matches 's'. The parameter represents a path. In some cases (such as array databag), this operation has no meaning. In such cases this function sets 'pi' to a non-zero error code and returnes string_o::bad_reference().
 

get_dbag()
SIGNATURE: dbag_o &get_dbag (count_t idx, int *pi = NULL) const
SYNOPSIS:
gets the 'nth' databag contained within the current object. Calling this member function, though legal, has no sensible meaning for this particular [base] class class, since the dbag_o class does not and can not contain other databags (unlike several other types of databags, such as list or recursive).
Generally, this function is applicable to list or recursive databags. Given a bag with this [top-level] structure:

char *dbag_TP =
"top_name
(
    first_item (name more_data)
    second_item < col0 col1 col2>
    third_item (more (x y))
)";

get_dbag(0) will retrieve "first_item" (as a databag), get_dbag(1) will retrieve "second_item", and so on.
PARAMETERS

• idx: index into a list of sub-children databags. First element is idx == 0. This parameter, in this case [eg this class], it has absolutely no significance and is ignored.
• pi: [optional] error indicator variable. This always returns 1

RETURNS: reference ["pointer"] to self - eg, "*this".
TRAITS: PURE VIRTUAL FUNCTION.
 

get_dbag()
SIGNATURE: dbag_o &get_dbag (const string_o &s, int *pi = NULL) const
SYNOPSIS:
Gets a databag contained within the current databag whose name matches the first parameter, 's'. In this case [eg this class], this parameter has no real significance.
PARAMETERS

• s: string object containing the name of the databag to search for. For this class, this parameter is useless.
• pi: [optional] error indicator variable. If the name of the current databag object matches 's', this is 0; else, this is set to 1.

 

put()
SIGNATURE: int put (const string_o &snam, const string_o &sval, boolean stomp = FALSE, int *pi = NULL)
SYNOPSIS: This function is a stub. It represents the interface for doing a "put" operation. In this class specifically, it simply returns -1.
PARAMETERS

• snam: string object containing the name of the databag to search for.
• sval: the value to put
• stomp: if TRUE, the object is designated as having been modified. if FALSE (the default), the "is-modified" status depends on whether the updated value has changed.
• pi: [optional] error indicator variable. This here is always set to zErr_UnsupportedProto

RETURNS: -1
 

put_dbag()
SIGNATURE: int put_dbag (const dbag_o &bag, int *pi = NULL)
SYNOPSIS: This function is a stub. It represents the interface for doing a "put" operation. In this class specifically, it simply returns -1.
PARAMETERS

• bag: the bag to put inside the current object
• pi: [optional] error indicator variable. This here is always set to zErr_UnsupportedProto

RETURNS: -1
 

add_dbag()
SIGNATURE: int add_dbag (const dbag_o &bag, int *pi = NULL)
SYNOPSIS: adds a data bag into the current object
PARAMETERS

• bag: the bag to put inside the current object
• pi: [optional] error indicator variable. This here is always set to zErr_UnsupportedProto

RETURNS: -1
 

merge_dbag()
SIGNATURE: int merge_dbag (const dbag_o &bag, int *pi = NULL)
SYNOPSIS:
replace the databag item with the contents from 'd', or if the current object does not have the databag, it will be added to the current object.
For this class, this is a no-op.
PARAMETERS

• bag: the bag to put inside the current object
• pi: [optional] error indicator variable. This here is always set to zErr_UnsupportedProto

RETURNS: -1
 

contains()
SIGNATURE: boolean contains (const dbag_o &) const = 0
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]
 

print()
SIGNATURE: string_o print () const
SYNOPSIS: converts the databag to a string. The returned text is suitable for printing.
TRAITS: this function is inline, and simply maps to print(string_o &).
 

print()
SIGNATURE: string_o print (string_o &s) const
SYNOPSIS: converts the databag to a string. The returned text is suitable for printing.
PARAMETERS

• s: a string object to recieve the string form of the contents
• of the databag. The same contents is also returned, as a
• return parameter.

TRAITS: this function is inline, and simply maps to print(string_o &).
 

iprint()
SIGNATURE: const string_o &iprint (string_o &, const count_t) const = 0
SYNOPSIS:
this is "internal print", and is the actual function called by both print() and print(string_o &) member functions. For the (dbag_o) class, this function has no implementation. It is up to sub-clases to define how to print themselves.
TRAITS: this function is pure virtual. It must be defined in sub-clases.
 

set_deepmod()
SIGNATURE: int set_deepmod (boolean x = TRUE)
SYNOPSIS: turns on (or off, if x is FALSE) the global flag 'gmod_oncopy'
DESCRIPTION: see the discussion on is-modified on-copy operations in the main page about databags for the meaning of this function.
TRAITS: this is a static member function; do not call it with an object instance.
 

unset_deepmod()
SIGNATURE: int unset_deepmod ()
SYNOPSIS: turns off the global flag 'gmod_oncopy'
DESCRIPTION: see the discussion on is-modified on-copy operations in the main page about databags for the meaning of this function.
TRAITS: this is a static member function; do not call it with an object instance.
 

operator <<()
SIGNATURE: std::ostream &operator << (std::ostream &, const dbag_o &)
SYNOPSIS: [PENDING WORK - INCOMPLETE!!!]