Z Directory reference manual ("man" pages)

class ref name: event
category-group: people
layer: 7

synopsis.
An event object, represented by The event_o class is a simple object that is subclassed from the orthodox_o class. It exists in order to provide a way to record an event. The term "event" may be confusing, since events can exist in many different contexts - perhaps in all contexts: historical event, astonomical event, subatomic physics, politics, etc. However, "event" best describes this object since it is free from any context. Its original intended purpose relates to sales force automation, and it can effectively log a note that is applied to an entity such as a business.

One can store and retrieve events from a database. All events get saved to the event table. This table has basically 3 columns (besides the standard set of columns provided by the orthodox object):

date_occured - when the event happened. The resolution is down to the second.
free_text - this is a user-defined summary (30 character maximum) of the event.
memo - this is the text you provid that describes the event. There is no theoretical limit to its size (it is of type "text" in the database).

description.
The event object was designed as a way to maintain and express a historical log of events in the context of interacting with a business. This could be used for job hunting or with the intent of sellng something to the business (job hunting could be considered a special case of this application, ie, selling one's services). Such a log is vital to knowing and remembering what was done, in order to take things to the next level. This is classic Sales Force Automation (SFA). A business has a specific format when printing it out as text.

An event is almost always in the context of an owner object. As discussed in the orthodox_o class, many orthodox objects can be owned by other orthodox objects: a telephone can be owned by a person, a worker, or a business. Likewise for an e-mail or postal address. All of these objects are sub-classes of orthodox_o. In the database context, these objects are maintained as a single row in a database. All such rows have standard orthodox columns such as owner, owner_tabid, source, and found. The first two, if the values are non-zero, indicate that the object is "owned" (belongs to) another [orthodox] object. The "owner" column value refers to the value of the "id" column in the database table that owns the object, and thhe "owner_tabid" indicates which table (and hence, what object). These tables (and corresponding objects) are not limited to Z Directory-specific classes - they can be your own inventions.

Since the event object is a subclass of orthodox_o, one should be somewhat familiar with the orthodox object and how to use it - more complex orhodox objects such as business or worker are good sources of this information. This class has the following database schema:

event
(
    is_equipment YES
    is_code      NO
    columns
    [
      <name  type   qual nulls_ok is_uniq     ref_table ref_column default check>
      <date_occured  datetime \"year to second\"  YES  NO  \"\"  \"\"  \"\"  \"\" >
      <free_text     char     30                  YES  NO  \"\"  \"\"  \"\"  \"\" >
      <memo          text     \"\"                YES  NO  \"\"  \"\"  \"\"  \"\" >
    ]
    sub_tables < >
    indexes
    (
        event_date_idx
        (
            is_cluster NO
            is_unique  YES
            is_ascend  NO
            is_descend NO
            columns <owner_tabid owner date_occured>
        )
    )
    foreign_key
    [
        <source_column dest_table dest_column>
    ]

Two items of note here: the data maintained here is extremely simple, consisting of date_occured, free_text, and memo. Of these, free_text can be safely ignored (and may possibly get phased out). Secondly, there is a unique index based on the columns owner_tabid + owner + date_occured. The part "owner_tabid + owner" refers to the object (as a database record) that owns the event. The last part of this unique index, "date_occured", indicates that no two events belonging to the same object can have the same exact time (and date).

printing an event - string representation and formatting.

The Z Directory uses a strict, specific text representation for many of its orthodox objects, including phone numbers, e-mail addresses, postal addresses, workers and businesses. The printing of a business - that is, formatting a business's data as a string - encompasses the formatting of most of these objects. Here is an example:

Acme Widgets, Inc. 100 Main Street Anytown, DC 20050 USA

phone: +1 (212) 555-1414 arpa: info@acme.com who: John Q. Public title: CEO loc: Anytown Suzie Que title: secretary boss: John Q. Public events: 04/06/1998: earliest known work done on the event object 08/17/2013: this example was made up 12/31/2013: Acme was contacted in order to find the price of one of its widget

If the text above is put into a string object (a string_o), it can be readily parsed by Z Directory components and the data saved to a database. The data in the example above would generate 1 business object, 1 phone number and 1 e-mail address object, 2 worker objects, and 3 events. Every detail would be parsed. This can be accomplished in as little as about 3 lines of code.

Note that events are a "repeatable block". Each event is preceded by a TAB (0x8) character at the start of a line, and if the event spans more than one line, it is continued by indenting with another tab character - that is, 2 tab characters at the start of a line continues the event. The body text of the event object - saved to the database memo column - can be anything you want.

One problem that presents itself is if an event happens at exactly the same time as another (at least, within the same second). An example is an e-mail application that groups e-mails by business, and the application encounters multiple emails that have the exactly the same date (perhaps it's a really popular organization that recieves thousands of emails per day). In this case, when events are added to the business object (or "organization".. the business_o class is used to store both businesses and other types of organizations), and then the business object is saved to a database, the attempt at storing the events with the same timestamp as events with a matching timestamp will fail. For this case, the event object can operate in an "auto-date-increment" mode. It works like this: when an event is attempted to be saved to the database, and the attempt fails because the event's timestamp matches that of another event with the same owner, the event object's timestamp is advanced by 1 second and the save is retried. This action will be repeated until the record is saved - that is, until a time (/date) is found that has not been used (which should under "normal" circumstances rarely exceed 1 iteration). By default, this mode is off.

member functions (primary)

event_o()
SIGNATURE: event_o ()
SYNOPSIS:
creates an empty event object. no fields are set at this point. all global-level orthodox initialization is performed (1-time action). The internal time object's format string is set to the default value ("dbbi_o::TIME_FORMAT").
TRAITS: this is an inline function

event_o(event_o)
SIGNATURE: event_o (const event_o &that)
SYNOPSIS:
initializes a new event object and copies the contents of 'that' to itself. This does not over-ride the orthodox base class ID. All event-specific variables are copied, including 'm_when', 'm_swhen', 'm_memo', and 'my_isset'.
TRAITS: this is an inline function

operator = (event_o)
SIGNATURE: const event_o &operator = (const event_o &that)
SYNOPSIS: copies the data in 'that' into the current object.
TRAITS: this is an inline function

destructor
SIGNATURE: ~event_o ()
SYNOPSIS: "destroy"s the object. All internal variable values are wiped clean and the object is set to the "not set" state.
TRAITS: this is a virtual function

event_o(<args>)
SIGNATURE: event_o (const string_o &s)
SYNOPSIS: constructs a new event object from a full string representation of an event in 's'.
PARAMETERS
s: [input] string containing the text for an event, starting with a date part. The string can be multi-line. The format of the date is described above. Here is an example of a valid string:
"07/20/1969: Neil Armstrong stepped on the moon\nOSSFM\n"
DESCRIPTION:
This constructor initializes the object from the given string, in variable 's'. The string must have a valid representation of the event, in order for the initialization to succeed. Otherwise, the result will be exactly the same as if via the default constructor.
The text's syntax is like so: "mm/dd/yyyy: \nmore text\n", where "mm" is a month number (1-12), "dd" is a day of the month (1-31), and "yyyy" is a 4-digit year. Note that no tab is expected to be at the first character of each additional line.

event_o(<args>)
SIGNATURE: event_o (const string_o &s_time, const string_o &s_note)
SYNOPSIS:
This constructor initializes the object, setting the event time to the value found in 's_time', and setting the memo (the body text that describes the event) to the text in 's_note'. The object is not saved to a database - it exists as a local instance after construction.
PARAMETERS

s_time: [input] string containing the time of an event ("time" in the Z Directory includes date). The format of the time should be "mm/dd/yyyy" or "mm/dd/yyyy hh:mm:ss".

s_note: [input] string containing the body text of the event

clone()
SIGNATURE: event_o *clone () const
SYNOPSIS:
makes an exact copy of the event object. a pointer to the new object is returned. You must explicitly use delete to clean up the object after done with it:

event_o e ("08/09/1974 12:00:00", "Richard Nixon resigns the\ American presidency in the face of certain impeachment\n\ Gerald Ford is sworn in as the 38th American President\n");
event_o *my_copy = e.clone(); // use 'my_copy' delete my_copy;

TRAITS: this function is inline

bad_reference()
SIGNATURE: const event_o &bad_reference ()
SYNOPSIS:
This returns a reference to the standard "bad variable" for the class. It is used to check for errors by functions that return a reference and cannot set an external error flag, such as an assignment operator.
TRAITS:
this is a static member function. Here is an example of how to call it:
const event_o myev; const event_o &my_result = myev.func_returns_refence(); const event_o &er = event_o::bad_reference(); if (&my_result == &er) { // pointers match the bad reference object; // therefore, the function "errored out" }

operator <<()
SIGNATURE: friend std::ostream &operator << (std::ostream &str, const event_o &ev)
SYNOPSIS: prints out the event to the ostream. This uses "print()" to format the text (which see).

operator = (event_o)
SIGNATURE: orthodox_o &operator = (const rec_dbag_o &bag)
SYNOPSIS: copies the data in databag 'bag' into the current object.

operator !=()
SIGNATURE: int operator != (const event_o &that) const
SYNOPSIS:
this function returns 0 or 1, depending on if the current object is considered equivelent to the object 'that'. See the entry for "operator == " for the definition of equivalence.
RETURNS:
1: objects are different
0: objects are the same
TRAITS: this function is inline

operator ==()
SIGNATURE: int operator == (const event_o &that) const
SYNOPSIS:
this function returns 1 if the current object is considered to be equivelent to the object 'that', or 0 otherwise. Two event objects are considered equal if their owner ID and table IDs are the same, and if the event time is exactly the same.
RETURNS:
1: objects are the same
0: objects are different

is_set()
SIGNATURE: boolean is_set () const
SYNOPSIS: tells if the object has been set to a valid event. This means the object's time has been set, and it has text for the event.
TRAITS: this function is inline

event_isset()
SIGNATURE: boolean event_isset (int *pi = NULL)
SYNOPSIS: tells if the object has been set to a valid event. This function is simply an alias for is_set().
PARAMETERS
pi: [optional] error indicator variable. Its value as of this writing is always 0.

isset_fixtime()
SIGNATURE: boolean isset_fixtime () const
SYNOPSIS: tells if the internal variable 'my_autoadvance' is set
TRAITS: this function is inline

when()
SIGNATURE: stime_o when () const
SYNOPSIS:
returns the event's time, as a string-time (stime_o) object. This function is semantically equivalent to timestring().

timestring()
SIGNATURE: const string_o timestring () const
SYNOPSIS:
returns the event's time. This is stored in databag "date_occured". If the object has not been set, an empty string ("") is returned.

memo()
SIGNATURE: const string_o &memo () const
SYNOPSIS: returns a reference to the string holding the text for the event (this is in the "memo" databag).
TRAITS: this function is inline

string_o conversion operator()
SIGNATURE: operator string_o () const
SYNOPSIS:
"converts" an event object to a string object. This operator function is simply an alias to the print() member function.

set_time()
SIGNATURE: int set_time (const stime_o &x, int *pi = NULL)
SYNOPSIS:
sets the time of the event. if the text has already been set (ie, done earlier), the event is considered to be set, and its state will be set to "is set".
PARAMETERS

x: [input] time object containing the time of the event. the object must be set to a valid time in order for this function call to succeed.

pi: [optional output] error indicator variable. Its value is set to one of the following:
0: success; time was set;
zErr_Param_NotSet: input variable 'x' not set to a valid time

set_text()
SIGNATURE: int set_text (const string_o &s, int *pi = NULL)
SYNOPSIS:
sets the body text of the event. if the time has been set earlier, the event is considered to be set, and the object's state will become "is set". The internal variable that is set is in the databag "background panel"; the path is "memo".
PARAMETERS

s: [input] text string. must be non-empty (use reset() to unset the object's contents) in order for this function call to succeed.

pi: [optional output] error indicator variable. Its value is set to one of the following:
0: success; memo-text was set;
zErr_Param_NotSet: input variable 's' is an empty string

settime_autofix()
SIGNATURE: int settime_autofix (const boolean onoff = TRUE)
SYNOPSIS:
turns on (or off) the internal flag for looking up the "next available time slot" in the database. This feature is used during calls to store_add() and store_update().
PARAMETERS
onoff: [input] boolean flag variable. if set (the default), the internal variable 'my_autoadvance' is set to TRUE; FALSE otherwise.

set()
SIGNATURE: int set (const stime_o &t, const string_o &s)
SYNOPSIS: sets the event.
PARAMETERS

t: a stime ("string time") object.

s: the text to pass to the "memo" part of the event.

set()
SIGNATURE: int set (const string_o &st, const string_o &sm)
SYNOPSIS: sets the event.
PARAMETERS

st: a string containing the time of the event.

sm: the text to pass to the "memo" part of the event.

settime_autofix()
SIGNATURE: int settime_autofix (const boolean onoff = TRUE)
SYNOPSIS: sets the internal boolean-flag variable 'my_autoadvance' to the value of 'onoff'
PARAMETERS
onoff: [input] boolean value (either TRUE or FALSE) that sets the internal boolean variable regulating auto-advancing the event object's time
RETURNS: 0 (always)

print()
SIGNATURE: string_o print () const
SYNOPSIS:
formats the object's data as a text string. If the object has not been set, an empty string is returned. The format of the output text (for set events) is "[date]: [memo]" (without the sqauare braces). The "date_occurred" field is separated from the "memo" field by 2 characters, a ": ".

store_update()
SIGNATURE: int store_update (int *pi = NULL)
SYNOPSIS:
overloads the base class (orthodox_o) store_update() function. This does some minor validation before forwarding the operation to the base class.
TRAITS: this is a reimplementation of a base class virtual function

store_add()
SIGNATURE: int store_add (int *pi = NULL)
SYNOPSIS:
overloads the base class (orthodox_o) store_add() function. This checks if the auto-advance flag is set, and if so, checks if there is already a matching database record. If so, the object's time will be advanced by the least amount of time required to be able to save the record. The operation is then forwarded the operation to the base class.
TRAITS: this is a reimplementation of a base class virtual function

reset()
SIGNATURE: int reset ()
SYNOPSIS: resets the object. The object will be "unset" and have no time-date value or memo text.

hava_goodtime()
SIGNATURE: int hava_goodtime (const event_o &that, int *pi = NULL);
SYNOPSIS:
compares the object's time to the time in 'that'. If the times are exactly the same (down to the second), the current object time is advanced by 1 second.
PARAMETERS

that: [input] string-time object that is used to compare the time with.

pi: [output] error indicator variable. values:
0: successful time check (and possibly set)
zErr_NoData: "date_occured" databag value is not set in either the current object ("this") or 'that'.

DESCRIPTION:
this member function is a quick way to make sure that two events do not have the exact same time (+ date). Unlike the sibling function with the same name, this always advances the object's internal time if the time-dates are equal.
RETURNS:
0: successful check-and-set
-1: 1 or more times were found to be not set

hava_goodtime()
SIGNATURE: int hava_goodtime (stime_o &t, const boolean setit = FALSE, int *pi = NULL)
SYNOPSIS:
looks up the "next available time slot" in the database for the object. Time and owner must be pre-loaded into the object in order for this function call to succeed. Calling this function has no side-effects; it does a data lookup only.
PARAMETERS

t: [output] string-time object that is set to the first available date.

setit: [input] if TRUE, the object will get set to the time stored in 't' (if the time has advanced, minimum 1 second)

pi: [output] error indicator variable. values:
0: success
zErr_NoData: "date_occured" databag value not set
zErr_DB_Cannot_Fetch: error trying to access event table
zErr_SameData: the time has not changed (it was safe to use originally). This is a notification only; not an error.

DESCRIPTION:
This function presupposes that the event's owner has been set, as well as the event time. Also, the object must be able to access a database containing the event table. If there are database records in the event table with the same owner and time, the object's time will be advanced by 1 second and the check is repeated. This will loop until an unused time is found. The time is returned in the first parameter, 't'.

format_time_todb()
SIGNATURE: int format_time_todb (string_o &sold, string_o &snew, const boolean wipe = TRUE, int *pi = NULL)
SYNOPSIS:
this function returns the currently existing string in the databag path "date_occured", and formats the time into a string required by the current database. This string is returned as output parameter 'snew'. If 'wipe' is set to TRUE (the default), the internal value for "date_occured" will be over-written by the contents also returned in 'snew'.
This function was designed to support database table modifications, and is not expected to be of much use for applications. If you use it with 'wipe' set to TRUE, it is your responsibility to manage the contents of the "date_occured" simple databag. As a support routine for other parts of event_o, the value saved into 'sold' is restored into its original location after the operation.

history.

??? 04/06/1998: added 2 extra bytes to "date_occured" in table schema
??? 10/13/1998: timestring() - junked using internal m_when, m_swhen
Thu 05/30/2002: took out the "biz" in "event" objects
Thu 09/19/2002: moved date_occured to datetime qual; also in free_text
Sat 09/28/2002: adding unique index on "date_occured" field.
Mon 06/17/2013: event_o::set(): time-date formatting cleaned up some
Sat 08/17/2013: added auto-time-advance mode

Vettrasoft Z Directory > tech support > reference > event (people group)
ref home support home samples contact
	class ref name: event category-group: people layer: 7 synopsis. An event object, represented by The event_o class is a simple object that is subclassed from the orthodox_o class. It exists in order to provide a way to record an event. The term "event" may be confusing, since events can exist in many different contexts - perhaps in all contexts: historical event, astonomical event, subatomic physics, politics, etc. However, "event" best describes this object since it is free from any context. Its original intended purpose relates to sales force automation, and it can effectively log a note that is applied to an entity such as a business. One can store and retrieve events from a database. All events get saved to the event table. This table has basically 3 columns (besides the standard set of columns provided by the orthodox object): date_occured - when the event happened. The resolution is down to the second. free_text - this is a user-defined summary (30 character maximum) of the event. memo - this is the text you provid that describes the event. There is no theoretical limit to its size (it is of type "text" in the database). description. The event object was designed as a way to maintain and express a historical log of events in the context of interacting with a business. This could be used for job hunting or with the intent of sellng something to the business (job hunting could be considered a special case of this application, ie, selling one's services). Such a log is vital to knowing and remembering what was done, in order to take things to the next level. This is classic Sales Force Automation (SFA). A business has a specific format when printing it out as text. An event is almost always in the context of an owner object. As discussed in the orthodox_o class, many orthodox objects can be owned by other orthodox objects: a telephone can be owned by a person, a worker, or a business. Likewise for an e-mail or postal address. All of these objects are sub-classes of orthodox_o. In the database context, these objects are maintained as a single row in a database. All such rows have standard orthodox columns such as owner, owner_tabid, source, and found. The first two, if the values are non-zero, indicate that the object is "owned" (belongs to) another [orthodox] object. The "owner" column value refers to the value of the "id" column in the database table that owns the object, and thhe "owner_tabid" indicates which table (and hence, what object). These tables (and corresponding objects) are not limited to Z Directory-specific classes - they can be your own inventions. Since the event object is a subclass of orthodox_o, one should be somewhat familiar with the orthodox object and how to use it - more complex orhodox objects such as business or worker are good sources of this information. This class has the following database schema: event ( is_equipment YES is_code NO columns [ <name type qual nulls_ok is_uniq ref_table ref_column default check> <date_occured datetime \"year to second\" YES NO \"\" \"\" \"\" \"\" > <free_text char 30 YES NO \"\" \"\" \"\" \"\" > <memo text \"\" YES NO \"\" \"\" \"\" \"\" > ] sub_tables < > indexes ( event_date_idx ( is_cluster NO is_unique YES is_ascend NO is_descend NO columns <owner_tabid owner date_occured> ) ) foreign_key [ <source_column dest_table dest_column> ] Two items of note here: the data maintained here is extremely simple, consisting of date_occured, free_text, and memo. Of these, free_text can be safely ignored (and may possibly get phased out). Secondly, there is a unique index based on the columns owner_tabid + owner + date_occured. The part "owner_tabid + owner" refers to the object (as a database record) that owns the event. The last part of this unique index, "date_occured", indicates that no two events belonging to the same object can have the same exact time (and date). printing an event - string representation and formatting. The Z Directory uses a strict, specific text representation for many of its orthodox objects, including phone numbers, e-mail addresses, postal addresses, workers and businesses. The printing of a business - that is, formatting a business's data as a string - encompasses the formatting of most of these objects. Here is an example: Acme Widgets, Inc. 100 Main Street Anytown, DC 20050 USA phone: +1 (212) 555-1414 arpa: info@acme.com who: John Q. Public title: CEO loc: Anytown Suzie Que title: secretary boss: John Q. Public events: 04/06/1998: earliest known work done on the event object 08/17/2013: this example was made up 12/31/2013: Acme was contacted in order to find the price of one of its widget If the text above is put into a string object (a string_o), it can be readily parsed by Z Directory components and the data saved to a database. The data in the example above would generate 1 business object, 1 phone number and 1 e-mail address object, 2 worker objects, and 3 events. Every detail would be parsed. This can be accomplished in as little as about 3 lines of code. Note that events are a "repeatable block". Each event is preceded by a TAB (0x8) character at the start of a line, and if the event spans more than one line, it is continued by indenting with another tab character - that is, 2 tab characters at the start of a line continues the event. The body text of the event object - saved to the database memo column - can be anything you want. One problem that presents itself is if an event happens at exactly the same time as another (at least, within the same second). An example is an e-mail application that groups e-mails by business, and the application encounters multiple emails that have the exactly the same date (perhaps it's a really popular organization that recieves thousands of emails per day). In this case, when events are added to the business object (or "organization".. the business_o class is used to store both businesses and other types of organizations), and then the business object is saved to a database, the attempt at storing the events with the same timestamp as events with a matching timestamp will fail. For this case, the event object can operate in an "auto-date-increment" mode. It works like this: when an event is attempted to be saved to the database, and the attempt fails because the event's timestamp matches that of another event with the same owner, the event object's timestamp is advanced by 1 second and the save is retried. This action will be repeated until the record is saved - that is, until a time (/date) is found that has not been used (which should under "normal" circumstances rarely exceed 1 iteration). By default, this mode is off. member functions (primary) event_o() SIGNATURE: event_o () SYNOPSIS: creates an empty event object. no fields are set at this point. all global-level orthodox initialization is performed (1-time action). The internal time object's format string is set to the default value ("dbbi_o::TIME_FORMAT"). TRAITS: this is an inline function event_o(event_o) SIGNATURE: event_o (const event_o &that) SYNOPSIS: initializes a new event object and copies the contents of 'that' to itself. This does not over-ride the orthodox base class ID. All event-specific variables are copied, including 'm_when', 'm_swhen', 'm_memo', and 'my_isset'. TRAITS: this is an inline function operator = (event_o) SIGNATURE: const event_o &operator = (const event_o &that) SYNOPSIS: copies the data in 'that' into the current object. TRAITS: this is an inline function destructor SIGNATURE: ~event_o () SYNOPSIS: "destroy"s the object. All internal variable values are wiped clean and the object is set to the "not set" state. TRAITS: this is a virtual function event_o(<args>) SIGNATURE: event_o (const string_o &s) SYNOPSIS: constructs a new event object from a full string representation of an event in 's'. PARAMETERS s: [input] string containing the text for an event, starting with a date part. The string can be multi-line. The format of the date is described above. Here is an example of a valid string: "07/20/1969: Neil Armstrong stepped on the moon\nOSSFM\n" DESCRIPTION: This constructor initializes the object from the given string, in variable 's'. The string must have a valid representation of the event, in order for the initialization to succeed. Otherwise, the result will be exactly the same as if via the default constructor. The text's syntax is like so: "mm/dd/yyyy: \nmore text\n", where "mm" is a month number (1-12), "dd" is a day of the month (1-31), and "yyyy" is a 4-digit year. Note that no tab is expected to be at the first character of each additional line. event_o(<args>) SIGNATURE: event_o (const string_o &s_time, const string_o &s_note) SYNOPSIS: This constructor initializes the object, setting the event time to the value found in 's_time', and setting the memo (the body text that describes the event) to the text in 's_note'. The object is not saved to a database - it exists as a local instance after construction. PARAMETERS s_time: [input] string containing the time of an event ("time" in the Z Directory includes date). The format of the time should be "mm/dd/yyyy" or "mm/dd/yyyy hh:mm:ss". s_note: [input] string containing the body text of the event clone() SIGNATURE: event_o clone () const SYNOPSIS: makes an exact copy of the event object. a pointer to the new object is returned. You must explicitly use delete to clean up the object after done with it: event_o e ("08/09/1974 12:00:00", "Richard Nixon resigns the\ American presidency in the face of certain impeachment\n\ Gerald Ford is sworn in as the 38th American President\n"); event_o my_copy = e.clone(); // use 'my_copy' delete my_copy; TRAITS: this function is inline bad_reference() SIGNATURE: const event_o &bad_reference () SYNOPSIS: This returns a reference to the standard "bad variable" for the class. It is used to check for errors by functions that return a reference and cannot set an external error flag, such as an assignment operator. TRAITS: this is a static member function. Here is an example of how to call it: const event_o myev; const event_o &my_result = myev.func_returns_refence(); const event_o &er = event_o::bad_reference(); if (&my_result == &er) { // pointers match the bad reference object; // therefore, the function "errored out" } operator <<() SIGNATURE: friend std::ostream &operator << (std::ostream &str, const event_o &ev) SYNOPSIS: prints out the event to the ostream. This uses "print()" to format the text (which see). operator = (event_o) SIGNATURE: orthodox_o &operator = (const rec_dbag_o &bag) SYNOPSIS: copies the data in databag 'bag' into the current object. operator !=() SIGNATURE: int operator != (const event_o &that) const SYNOPSIS: this function returns 0 or 1, depending on if the current object is considered equivelent to the object 'that'. See the entry for "operator == " for the definition of equivalence. RETURNS: 1: objects are different 0: objects are the same TRAITS: this function is inline operator ==() SIGNATURE: int operator == (const event_o &that) const SYNOPSIS: this function returns 1 if the current object is considered to be equivelent to the object 'that', or 0 otherwise. Two event objects are considered equal if their owner ID and table IDs are the same, and if the event time is exactly the same. RETURNS: 1: objects are the same 0: objects are different is_set() SIGNATURE: boolean is_set () const SYNOPSIS: tells if the object has been set to a valid event. This means the object's time has been set, and it has text for the event. TRAITS: this function is inline event_isset() SIGNATURE: boolean event_isset (int pi = NULL) SYNOPSIS: tells if the object has been set to a valid event. This function is simply an alias for is_set(). PARAMETERS pi: [optional] error indicator variable. Its value as of this writing is always 0. isset_fixtime()* SIGNATURE: boolean isset_fixtime () const SYNOPSIS: tells if the internal variable 'my_autoadvance' is set TRAITS: this function is inline when() SIGNATURE: stime_o when () const SYNOPSIS: returns the event's time, as a string-time (stime_o) object. This function is semantically equivalent to timestring(). timestring() SIGNATURE: const string_o timestring () const SYNOPSIS: returns the event's time. This is stored in databag "date_occured". If the object has not been set, an empty string ("") is returned. memo() SIGNATURE: const string_o &memo () const SYNOPSIS: returns a reference to the string holding the text for the event (this is in the "memo" databag). TRAITS: this function is inline string_o conversion operator() SIGNATURE: operator string_o () const SYNOPSIS: "converts" an event object to a string object. This operator function is simply an alias to the print() member function. set_time() SIGNATURE: int set_time (const stime_o &x, int pi = NULL) SYNOPSIS: sets the time of the event. if the text has already been set (ie, done earlier), the event is considered to be set, and its state will be set to "is set". PARAMETERS x: [input] time object containing the time of the event. the object must be set to a valid time in order for this function call to succeed. pi: [optional output] error indicator variable. Its value is set to one of the following: 0: success; time was set; zErr_Param_NotSet: input variable 'x' not set to a valid time set_text()* SIGNATURE: int set_text (const string_o &s, int pi = NULL) SYNOPSIS: sets the body text of the event. if the time has been set earlier, the event is considered to be set, and the object's state will become "is set". The internal variable that is set is in the databag "background panel"; the path is "memo". PARAMETERS s: [input] text string. must be non-empty (use reset()* to unset the object's contents) in order for this function call to succeed. pi: [optional output] error indicator variable. Its value is set to one of the following: 0: success; memo-text was set; zErr_Param_NotSet: input variable 's' is an empty string settime_autofix() SIGNATURE: int settime_autofix (const boolean onoff = TRUE) SYNOPSIS: turns on (or off) the internal flag for looking up the "next available time slot" in the database. This feature is used during calls to store_add() and store_update(). PARAMETERS onoff: [input] boolean flag variable. if set (the default), the internal variable 'my_autoadvance' is set to TRUE; FALSE otherwise. set() SIGNATURE: int set (const stime_o &t, const string_o &s) SYNOPSIS: sets the event. PARAMETERS t: a stime ("string time") object. s: the text to pass to the "memo" part of the event. set() SIGNATURE: int set (const string_o &st, const string_o &sm) SYNOPSIS: sets the event. PARAMETERS st: a string containing the time of the event. sm: the text to pass to the "memo" part of the event. settime_autofix() SIGNATURE: int settime_autofix (const boolean onoff = TRUE) SYNOPSIS: sets the internal boolean-flag variable 'my_autoadvance' to the value of 'onoff' PARAMETERS onoff: [input] boolean value (either TRUE or FALSE) that sets the internal boolean variable regulating auto-advancing the event object's time RETURNS: 0 (always) print() SIGNATURE: string_o print () const SYNOPSIS: formats the object's data as a text string. If the object has not been set, an empty string is returned. The format of the output text (for set events) is "[date]: [memo]" (without the sqauare braces). The "date_occurred" field is separated from the "memo" field by 2 characters, a ": ". store_update() SIGNATURE: int store_update (int pi = NULL) SYNOPSIS: overloads the base class (orthodox_o) store_update()* function. This does some minor validation before forwarding the operation to the base class. TRAITS: this is a reimplementation of a base class virtual function store_add() SIGNATURE: int store_add (int pi = NULL) SYNOPSIS: overloads the base class (orthodox_o) store_add()* function. This checks if the auto-advance flag is set, and if so, checks if there is already a matching database record. If so, the object's time will be advanced by the least amount of time required to be able to save the record. The operation is then forwarded the operation to the base class. TRAITS: this is a reimplementation of a base class virtual function reset() SIGNATURE: int reset () SYNOPSIS: resets the object. The object will be "unset" and have no time-date value or memo text. hava_goodtime() SIGNATURE: int hava_goodtime (const event_o &that, int pi = NULL); SYNOPSIS: compares the object's time to the time in 'that'. If the times are exactly the same (down to the second), the current object time is advanced by 1 second. PARAMETERS that: [input] string-time object that is used to compare the time with. pi: [output] error indicator variable. values: 0: successful time check (and possibly set) zErr_NoData: "date_occured" databag value is not set in either the current object ("this") or 'that'. DESCRIPTION: this member function is a quick way to make sure that two events do not have the exact same time (+ date). Unlike the sibling function with the same name, this always advances the object's internal time if the time-dates are equal. RETURNS: 0: successful check-and-set -1: 1 or more times were found to be not set hava_goodtime()* SIGNATURE: int hava_goodtime (stime_o &t, const boolean setit = FALSE, int pi = NULL) SYNOPSIS: looks up the "next available time slot" in the database for the object. Time and owner must be pre-loaded into the object in order for this function call to succeed. Calling this function has no side-effects; it does a data lookup only. PARAMETERS t: [output] string-time object that is set to the first available date. setit: [input] if TRUE, the object will get set to the time stored in 't' (if the time has advanced, minimum 1 second) pi: [output] error indicator variable. values: 0: success zErr_NoData: "date_occured" databag value not set zErr_DB_Cannot_Fetch: error trying to access event table zErr_SameData: the time has not changed (it was safe to use originally). This is a notification only; not an error. DESCRIPTION: This function presupposes that the event's owner has been set, as well as the event time. Also, the object must be able to access a database containing the event table. If there are database records in the event table with the same owner and time, the object's time will be advanced by 1 second and the check is repeated. This will loop until an unused time is found. The time is returned in the first parameter, 't'. format_time_todb()* SIGNATURE: int format_time_todb (string_o &sold, string_o &snew, const boolean wipe = TRUE, int pi = NULL) SYNOPSIS: this function returns the currently existing string in the databag path "date_occured", and formats the time into a string required by the current database. This string is returned as output parameter 'snew'. If 'wipe' is set to TRUE (the default), the internal value for "date_occured" will be over-written by the contents also returned in 'snew'. This function was designed to support database table modifications, and is not expected to be of much use for applications. If you use it with 'wipe' set to TRUE, it is your responsibility to manage the contents of the "date_occured" simple databag. As a support routine for other parts of event_o, the value saved into 'sold' is restored into its original location after the operation. history.* ??? 04/06/1998: added 2 extra bytes to "date_occured" in table schema ??? 10/13/1998: timestring() - junked using internal m_when, m_swhen Thu 05/30/2002: took out the "biz" in "event" objects Thu 09/19/2002: moved date_occured to datetime qual; also in free_text Sat 09/28/2002: adding unique index on "date_occured" field. Mon 06/17/2013: event_o::set(): time-date formatting cleaned up some Sat 08/17/2013: added auto-time-advance mode
home \|\| support \|\| FAQ \|\| get Z Dir \|\| contact us Copyright 2010 Vettrasoft Corporation - All Rights Reserved