class ref name: simpid_o
category-group: sql
layer: 0
header file: z_simpid.h
libraries: libz00.lib

synopsis.
the simpid_o class is an extremely simple and lightweight class. It logically does not fall into any existing group in the Z Directory, but since it is used almost exclusively by the orthodox object, it is lumped in with it into the sql group.

Its purpose is to maintain IDs for the object that contains it. Although this object is put into the sql group, can belong to any group and defies classification.

description.
The oid object contains 2 IDs: an internal ID and an external ID. The internal ID is assigned to a new object instance by a global sequential counter, working in the same way as an "auto increment primary key" works for a column field in a database table. The next number in the sequence is assigned (think of a ticket number machine at a meat counter). This number is put into the object's _oid internal variable (of type count_t ), and exists for the lifetime of the object. It is an immutable, fixed number. Not even a reset() will change or destroy this value. However, there is a loophole: you can use force_id() to change it via brute force.

The external number represents the object's ID in some external system - its "mirror". You can do whatever you want with this number; it is completely under application control. It is stored in the internal variable _eid . In the case of the orthodox_o class, this number is used when referencing the object in a database. That is, when you do orthodox_o::store_fetch(), loading a row in some database table into your object, the ID found in the "id" column of the table for the fetched row will go into the object's _eid variable of its oid object.

object assignment.

When an oid object is copied to another object, each of the IDs behave differently:

• _eid: the LHS (left-hand side, ie recipient) object's value is copied from the RHS (giver-donor) value. Thus, the external IDs become the same. Simple.
• _oid: the object internal IDs are treated like a football: the LHS variable recieves the value of the RHS variable. Thus, the value transfers. The donor can no longer have the same ID number: the RHS-donor object's _oid recieves a new value from the master ID counter. . However, this "take" action - a transfer - only applies to simpid_o that "belong" to an object. Another form of simple ID objects are used as references. In this context, such objects are called invalid objects.

invalid objects.

A simpid object can be made "invalid". this means that it cannot represent the ID for an object. This is useful for times when you need to copy the ID exactly, for comparing to other objects. Perhaps you want to pass the ID object around as a parameter to a function. Such objects are intended to be used briefly and their existance is temporary. Once made invalid, the object is permanently invalid - it cannot be made "valid". The ID values of invalid objects can be copied repeatedly:

  simpid_o a, b, c, d;
  a.set_invalid();
  b.set_invalid();
  c.set_invalid();
  b = a;                // ok; b is exact copy of a
  c = b;                // ok; c is exact copy of b (and of a)
  d = c;                // denied - d, c unchanged

templates and the object's evolution.

Prior to July 2013, this class was called oid_o and it was template-based. The object (constructor is included here) looked approximately like so:

template 
class oid_o
{
public:
    inline oid_o ();
private:
    static count_t master_id;
};

template  oid_o::oid_o()
{
    _oid = ++master_id;         // ie, local instance ID
    _eid = 0;
}

The goal of a template-based implementation was to provide each class with its own global counter (master_id). The problem with this idea is that it simply didn't work, in addition to providing a lot of needless excess complexity. Classes such as person_o or business_o are simply subclasses of orthodox_o (which has a very large family of subclasses), and do not implement their own "master id". Instead, they (and all the other sibling classes) rely on the orthodox_o::master_id. Its declaration:

count_t oid_o::master_id = 0;

The original intent of having individual counters, one per class, would be lost here becuase all derivative classes of orthodox would end up using only the orthodox counter.

Although separate counters would be nice, assuming each class restricted its ID operations to IDs solely of the given class, it is not really necessary. The primary goal of this counter is to provide unique ID values to an object. This is still maintained with a inter-class counter. The template implementation has been scrubbed.

member functions (primary)

simpid_o()
SIGNATURE: simpid_o()
SYNOPSIS:
creates a a new oid object. The 3 variables are set as follows:
The assigned _oid value is the next value of master_id.
The assigned _id value is the same as the _oid value.
The _eid value is 0.
 

simpid_o(simpid_o)
SIGNATURE: simpid_o (const simpid_o &that)
SYNOPSIS:
creates a a new object ID object. The object will recieve a new value for the _oid. The ID variables will be copied from 'that' according to the rules of object assignment (see main discussion on this page).
 

id()
SIGNATURE: count_t id () const
SYNOPSIS: returns the value of _id.
 

oid()
SIGNATURE: count_t oid () const
SYNOPSIS: returns the _oid value.
 

eid()
SIGNATURE: const count_t &eid () const
SYNOPSIS: returns the _eid value.
 

extern_id()
SIGNATURE: const count_t &extern_id () const
SYNOPSIS: returns the _eid value. This function is simply an alias for the eid() function.
 

operator ==()
SIGNATURE: int operator == (const simpid_o &that) const
SYNOPSIS: compares the current object to 'that' for equality.
DESCRIPTION: The 2 objects are considered equal if their _id values are the same.
RETURNS:
1: the objects are equivalent
0: the objects are different
 

operator = (simpid_o)
SIGNATURE: const simpid_o &operator = (const simpid_o &that)
SYNOPSIS:
The values of the 3 IDs in the current object take on the values of the corresponding parameters in 'that', according to the rules of assignment, specified above.
 

set_externID()
SIGNATURE: int set_externID (count_t x)
SYNOPSIS: sets _eid to x.
PARAMETERS

x: any integer value.

 

force_id()
SIGNATURE: int force_id (count_t x)
SYNOPSIS: sets _id to x.
PARAMETERS

x: any integer value.

 

reset()
SIGNATURE: int reset ()
SYNOPSIS: this function sets _id to -1 and sets _eid to 0.
 

note.
This class used to have 3 IDs. The third ID was called _id . It assumed the value of the _oid (object ID) by default. It was added in the hopes that when referencing an object's "ID", a single interface and value would suffice, and that this variable would represent a "logical ID". It would reset to 0 upon a reset() . It was to be used like a "primary key" in comparing 2 oid objects. The value would swap between the internal and external values, depending on if the object was designated as being local or not.

This turned out to be of questionable value and horribly confusing. It is now a historical relic.