Z DIRECTORY: REFERENCE MANUAL
Version ZP9, build 21
This section provides a reference manual for the individual components of
the Z Directory, and this web page is its entry point. The organization of
the 'man' pages starts with a category (sometimes called a group here).
Each category has its own web page. The categories page provides a description
of the components found in the category, across all layers. Categories can and
typically do span multiple layers. From there, you can access documentation
about the Z Directory components for that group. Components refer to functions
and classes.
The on-line manual pages in this reference section are specific to the latest
build (listed above). If you need earlier versions, please
contact Vettrasoft.
The second half of this page is organized by layers, starting with layer 0.
This is the only place in the reference manual where the sorting is layer
first, then category. This makes it hard if you want to see, say everything
related to file systems. Instead, you would have to dig through sections about
file systems at layer 0, file systems at layer 1, This page contains only brief
summary information. The current list of categories is this:
| name |
description |
| address |
clases to manage [postal, e-mail, ..] addresses |
|
|
an integral part of the Z Directory are basic, template-based
containers: linked lists, arrays, etc |
| dbag |
data bags represent a simple, easy-to-read protocol for putting
text into containers. The container is inside a string. These
containers can be parsed to extract a giving datum. Similar to
XML |
| documents |
some basic classes to manage a "document" |
| email |
a cluster of classes exist for creating, sending, and processing
e-mail messages. There are also classes for managing e-mail
servers, and webmail - a [currently] experimental class for sending
e-mail via web sites |
| errors |
The domain of error processing which includes tracing source code
and logging. In layer 0, you can access and control flag that
manage how to process errors.
|
| etc |
classes and subroutines are put here that are too small
to make a new group for, or defy categorization |
| exam |
a cluster of classes for exam questions and answers;
also with support (formatting) for web servers |
| files |
everything to manage files and directories
("folders", in Microsoft-speak) |
|
|
contains only 2 classes: "flag" and "property flag";
for setting flag values |
| geo |
functions for looking up geographical information -
countries, cities, landmarks, postal (zip) codes, and more.
Requires installing the geo database (included).
|
| io |
components to manage console input-output, and some [old]
classes to manage terminal [CRT] I/O |
| math |
a collection of functions that provide basic mathematical and
statistical operations exist. |
| money |
classes for handling money and doing [simple] accounting |
| networks |
higher-level constructs specific to the area of networking |
| os |
operating system- oriented classes and subroutines, dealing
with computer processes, semaphores, and threads. Also,
subroutines for accessing the [Microsoft-only] registry,
and an object for computers ("computer_o") as well
as some computer hardware components, such as a class for
CPUs and disk drives.
|
| people |
The "people" domain provides clases to help manage things such
as people, businesses, telephones, and workers |
| quickdirt |
'quick &: Dirty' classes and functions - mostly classes
to support the overall structure of console-based programs
and getting the user's input for interactive console-based
programs |
| security |
This group was not named "encryption" because the purpose of
encrypting data is to secure it, eg provide security. This group
will grow to include other things pertaining to security. For now,
the most notable components are a cluster of objects for encrypting
and decrypting bytes (this group was formerly named "crypt").
.
Encryption could fall under the "strings" domain, as all the ciphers
here operate on and modifies the contents of strings. Note that a
"string" in this context can be text - actual, readable words - or
bytes, such as from a computer program. Both can be stored in the
string_o class object.
Many encryption algorithms (Vettrasoft often refers to them as
"ciphers') are available, including all the well-known ones, such
as Rijndael, RSA, DES, blowfish and twofish.
.
There is also an object for user account access control (in layer 7).
|
| servers |
classes and functions that allow you to easily create your own
servers. Of course, a server is a complicated object. Vettrasoft
has strived to provide a base class to handle the common mechanics
that a server performs, such as listening for and processing
connections from clients.
|
| sql |
classes and support to access relational databases (based on
SQL). Requires a third-party database (eg, Sybase, Oracle,
mySQL, Informix, etc.). It includes a complete system for
storing your own objects (based on the 'orthodox_o'
class), similar to an O-O database. |
|
|
a large assortment of classes and subroutines for dealing with
strings and text, including classes for regular expression
processing, and components for calculating CRC checksums
and binry-to-text encode - decode (eg, uuencode and base 64).
|
| time |
a large assortment of classes and subroutines for setting and
measuring time. "time" in the Z Directory refers to dates, as well
as time of day. you can add time intervals (ie, 2 weeks) to a time,
or find the interval of time between to time [-date] objects
|
| transport |
"message transport" allows you to move a string from one
address point to another (eg, a circuit). The interface
hides the transport mechanism, but sockets are the most
commonly used in the Z Directory
|
| www |
support for web servers and CGI programs. Currently, this
is mainly the CGIclient object, which interfaces between
a web page form and a Z Directory server program. |
| xwin |
X Window support; mostly convenient aids to constructing
various widgets
|
Warning. This page, the pages underneath it, contains documentation
for the latest version of the publicly released Z Directory. The documentation
may vary from the version you have, if your version is different. Usually
the variations - including class object member functions and global subroutine
signitures - are minor. However, sometimes objects are added or removed,
or even overall functionality and behavior may change. So make sure your
Z Directory version matches the reference pages you are looking at.
If this documentatation differs markedly, please check the version you have.
If you cannot reconcile the differences between what is here and the
signitures you have in your header files, please contact Vettrasoft.
The current version (as documented here): Version ZP9, build 22
(March 2017)
Clicking on the links in this table will put you at the start page for
the category.
A synopsis of the contents, by layers, follows.
Layer 0
errors
a few minimal functions for configuring a program how to react
when an error is encountered.
etc
as the name implies, an assortment of things defying grouping into a
common purpose: functions compute sizes of built-in types (integer, long,
char, etc); bitwise operations on bytes (such as rotating bits); and a
simple state object that uses transition diagrams to maintain state.
files
simple functions to get and set the current working directory.
A set of subroutines to do basic disk file operations: create,
delete, test existence. These functions use char *
(simple, native language type) for file and directory names
in the function parameters.
flags
contains the flag_o and propflag_o class objects. These
are hard-working objects designed to maintain state information. they
are also known as "bit vectors". The "property flag" class is similar
to the flag class, but you can assign behaviours to the flags such
as if a flag can be inherited from a 'mother' instance, read-only,
and several other characteristics.
io
The "io" group contains a group of functions to handle getting input from
a console, such as z_getline_stdin(); some "convenience functions"
related to getting input, such as simply_get_yes() and
simply_get_number(); functions that interface between iostreams
and string objects; and a "tty" (tty = TeleTYpe) class. The latter is for
unix environments only. It gets and sets terminal modes; and handles
terminal I/O functions. This class is rusting, being rarely used nowadays.
math
common mathematical (and related) functions, including statistics,
getting and setting digits in a number, etc. Functions here include the
sum of a set of numbers, least common denominator, factors, if a number
is prime or divisible by another number, modulus, LUB, GLB, and others.
os
functions relating to the operating system: getting an environment
variable, host name, process ID (the PID), and thread objects.
For Unix environments, a function to "daemonize" a process.
quickdirt
Some "Quick & Dirty" items. In this layer, the menu loop class,
which is a construct for console applications to print a menu of
choices, get the user's selection, and call the corresponding code.
strings
A large group of functions (no classes here) that operate on or with the
"char *" data type, including: OS-wrappers such as z_stricmp(), z_strcpy(),
z_strcat(), z_strdup(), z_isdigit(), etc; stripping trailing whitespace
(like perl's chomp); copying binary strings, getting a line of input,
converting case, string - [type] conversion (such as int to long or
double, etc); number-to-string conversion functions, including special
ones for formatting as dollar amounts; much more
time
This contains only 'sleep()' routines, to put the program to sleep
www
contains a few simple support routines that web servers might use
xwin
This code is used only for interfacing with the [unix based] X Window
system
Layer 1
containers
contains only the "list axiom" (list_axiom_o) class: a root-base
class for all container classes. It is an abstract class necessary
for containers found in subsequent layers, not intended for public
use
email
contains "e-mail header" (email_header_o) and "e-mail message"
(email_msg_o) class
math
contains classes for angles and [mathematical] hashes.
operations on angles, including degree-radian conversion
os
contains classes for semaphores and threads
quickdirt
contains the classes "run driver" (rundriver_o) and "test driver"
(testdriver_o), Vettrasoft's objects for a standard interface to
typical command-line based programs that interact with a user at a
console. this "convenience code" allows for automating command-line
processing and protocol for main driver logic flow-control
strings
contains a class for strings ("string_o"). Similar to STL's
"string" class. this class is heavily used
Layer 2
address
contains the function z_IPaddress_to_hostname().
Since it uses string objects, it habitats in layer 2
containers
At this layer comes a Simple, template-based list-of-objects interface,
and a linked list. This place is rather ethereal, as almost all the code
exists entirely in the header files.
crypt
encryption and decryption cluster of classes, including crypt_o,
the generic interface to a variety of implementations (ROT-13, RSA,
Blowfish, 'simple hash', and Vettrasoft-proprietary)
email
here lies parent classes that establish the foundation for classes
relating to e-mail, found in higher layers
etc
Contains the "skeleton" class (z_Skeleton) - this special file
is a template file for creating other classes
money
contains the "money" class (money_o). Put your money into these
objects
os
holds 2 functions: z_hostid() and z_run_command()
quickdirt
contains the "simply" functions, such as simply_get_yes(),
which prints a prompt message and gets input from the user, in the
form of a yes/no reply
security
Encryption algorithms for encoding and decoding blocks of text,
or binary data (good for encrypting files). Several algorithms
are available, such as DES, RSA, and Blowfish. There is a singular
common interface for all.
sql
This layer marks the introduction of SQL support.
The "dbconnection_o" class is found here
strings
Here habitat more elaborate subroutines for strings, such as
z_wrap_text_in_quotes(), and the text string object
(textstring_o), a subclass of the string object. it
provides more powerful text-oriented operations. this location
also contains the regular expression class regex_o,
with which you can do string pattern matching using regular
expressions
time
contains the time class object (time_o), which you can set to a
specific time + date, or the current time. many operations are provided,
including telling if it's a leap year; getting the number of days in a
month; ++ and -- operators. this class is required for other classes
based on time, found at higher layers
xwin
contains subroutines for X Windows Motif, such as creating various widgets,
such as labels, text fields, and push buttons
Layer 3
dbag
Data bags are introduced here: data bags for lists, arrays, matrices;
recursive data bags. These objects hold strings of meta-data. The data bag
concept is similar to XML
email
contains the classes mapi_store_o and email_store_axiom_o.
These are internal classes related to e-mail operations
sql
contains "primitives" - fundamental operations for SQL-based RDBMS's.
3 access methods are currently available and implemented: ODBC, ADO,
and Informix's esql.
strings
provides more specialized string operations - "keywords"; parameter string
class ( paramstring_o), which defines a mechanism for passing
name-value pairs of strings amongst objects; and a set of subroutines
for more complex string-focused jobs:
z_extract_pattern() --- take out all matching regex patterns
z_find_anycase() --- find substring; upper- or lower- case
z_worded_number() --- given 25, this returns "twenty five"
z_num_to_ordstring() --- given 21, returns "21st", as a string
z_insert_ntabs_inline()
time
contains the "date format" class (datefmt_o), for printing out
time and date in a wide variety of formats. also contains the time span
class (timespan_o), which allows you to calculate the amount of
time between to time_o objects.
For time operations with string formatting skills, you may prefer the
"string-time" (stime_o) class - a child of the time object, found
at the next higher layer. The date-format class found here acts as a
support class for stime_o (however, its use is klunky)
transport
The first occurance of message transport heralds the "packet" class
(packet_o), which puts a string into a message packet
www
This contains only the function load_dbag_from_cgi_query_string(),
which loads a data bag given an CGI query string
xwin
More X-Windows Motif support, including an X-window Motif list widget class
(xmlist_o). and an assortment of utility functions, usually with
very long names, such as z_xm_create_toggle_box()
or z_xm_create_row_of_pushbuttons_onrowcol()
Layer 4
e-mail
contains classes for e-mail accounts (email_acct_o)
sql
Contains Database - [data] Bag Interface, or DBBI (pronounced "Debbie").
This class provides a mechanism to save a data bag into a database table.
It was originally written to accommodate the Informix database.
In the summer of 2001, a Microsoft Win32 COM/ADO version was developed,
with features to support concurrent access to a table. This provides the
foundation for the orthodox_o class object, found in layer 6.
strings
The "keyword parser" (
kw_parser_o )
class is here. It uses several internal, supporting classes, such as:
keyword_o, line_item_parser_o, text_item_parser_o, mblock_item_parser_o,
kw_schema_o. The purpose of the keyword parser is to take a line like so:
who: Maxwell Smart
and parse it. Well, there is a lot more to it: a keyword can span multiple
lines, or each line can mark the start of a new entry. An entry can have
sub-items:
who: Maxwell Smart
loc: variable
age: 32
phone: (212) 555-1212
Agent 99
age: 30
The Chief
age: 67
loc: Control HQ
url: http://getsmart.cbs.com
notes: this represents a TV series that terminated.
no further notes will be written about it here.
Please see the man page for more details.
time
Contains the class "string-time" (stime_o), which is basically
the time class (time_o) with string formatting capability.
Here also habitats the class "time period (timeperiod_o),
a currently [2011] experimental class for operations on time on a
recurring basis.
transport
The "packet buffer" (pktbuff_o) class resides here. This is used
in message transport - a Z Directory term referring to the act of moving
a block of bytes around, or what some may call networking.
www
contains classes designed to make HTML code management easier,
including "HTI_dbag_o", "HTI_text_o", "HTI_image_o", and "HTI_tabrow_o"
xwin
contains the class "xmlookup_o", for displaying a list of things
in x Windows / motif
Layer 5
dbag
Contains [only] the function "z_fetch_next_databag_fromfile()",
which returns successive data-bags stored in a file.
errors
Layer 5 marks the beginning of classes that handle error processing, logging,
and tracing. These are tools a developer can use to embed messages in the
code, dynamically set a level to control emission of messages, useful for
debugging and logging. Major classes include trace_o, error_o,
and announcement_o.
sql
Contains the class "database-table" (dbtable_o),
which manages database tables in an RDBMS. It uses data bags heavily,
as do many other classes at higher layers.
Layer 6
sql
The "orthodox" object, orthodox_o, is here. This object is so important,
it had its own group earlier. However, all its operations relate to [SQL]
database access, so the orthodox group was merged into sql on
August 11, 2012.
The orthodox_o class is a 'structural' componenent in the sense that it
doesn't apply to any real-world domain, but serves as a base class to other
classes that do. It allows you to save and fetch a class object to/from a
database. The name derives from James Coplien's purple book, where he
describes standard behaviors of a class with extended properties.
xwin
contains some esoteric operations: the "bgi2x" class, which maps
Borland Graphics Interface to X Window graphics calls; and "xmfdisp_item_o",
for displaying a set of X Window - Motif text widgets
Layer 7
address
an abstract base class for addresses (address_o) is realized here.
subclasses of the address class, at higher layers, will provide useful
objects for manipulation of many sorts of addresses
exam
The group of classses here (such as exam_question_text_o) may be a
little odd: they provide a mechanism for examinations. This was developed
in order to provide support for on-line, web-based testing systems.
money
Issues dealing with money focus on accounting here:
- account_o account object (as in Chart Of Accounts)
- vendor_o class object for vendor information
- bank_rec_o Bank reconciliation object
- check_entry_o Check-entry object
slq
contains the "orthodox database set" (orthodb_set_o),
used to copy-export a set of tables in a database.
people
contains 'people-oriented' classes: "phone number" class
(phone_number_o); "person" class (person_o);
"extended data" (xdata_o), and events (event_o).
Events are in the people-historical context - not computer-related
events. Extended Data is a class that supports the "business" class.
security
a class to manage user accounts is here (uacct_o).
this area deals with access permissions for users, which can
be applied to class objects.
Layer 8
address
contains classes for manipulating various addresses: e-mail
(email_address_o); internet addresses (internet_address_o),
referring to the 4 sets of dotted numbers (IPv4); and postal addresses
(postal_address_o), which can parse most any [American]
postal addresses into the components - street number, city, state, zip,
etc.
Note that the alternative category "email" to the e-mail address class
is not used, as an e-mail address is a type of address.
email
contains several classes to handle all things e-mail: e-mail servers,
messages, accounts, etc. Classes here include mapi_store_o,
email_header_o, and email_store_axiom_o
files
classes for manipulating file and directory addresses
(file_address_o, directory_address_o) - eg, a file name,
or the path of a directory. Note: a "file address" exemplifies the problem
of multiple inheritance - does this object belong in "files" or "address"?
transport
contains the class "message transport" (msgtrans_o). This is
the primary class used for moving a block of data across a circuit
exam
contains a couple functions only: examq_to_html(),
exam_to_html(). These routines take an exam class instance and format
the text to HTML. The group was formerly called "www_exam", reflecting the
[MI] nature of belonging to the web group and belonging to the domain of exams.
Layer 9
files
contains the major classes file and directory (file_o, directory_o).
You can do all common operations with these classes - create, delete,
copy, add / write, read, etc
networks
contains classes "proxy" (proxy_o) and "webpage spider"
(webpage_spider_o). These are highly experimental classes
subject to major changes in the future. We include but discourage
their use at present
servers
contains server databag class objects (server_dbag_o). this class
is not for public consumption. it provides support for communication
between servers
transport
contains a cluster of "message transport" classe using sockets for the
implementation. classes include:
msgtrans_socket_o ....: a top-level class for socket communication;
msgtrans_sockaddr_o ..: a class to hold the address of a socket;
msgtrans_inetsocket_o : class for inernet domain sockets;
msgtrans_unixsocket_o : class for unix domain sockets;
socket_channel_o .....: holds information about a circuit
(eg, if open; connected; if it's a server socket)
Layer 10
Layer 10 is a busy layer, covering many domains. a new category, "documents",
provides classes to manage a document. in the "people" domain, the "business"
class utilizes simpler people-domain objects (telphone number, postal address,
person) to manage information about a business.
crypt
contains class "filecrypt_header_o", used for encrypting files
documents
contains the document class (document_o), which manages document
properties - category, title, subject matter, character encoding, notes,
location, etc.; and a class for HTML documents (htmldoc_o)
files
contains [only] the routine "z_get_next_input_line()". This subroutine
employs file_o and string_o classes to get sequential input lines from
a text file or standard input
math
a class for a random number generator (RNG_o). 2 types of random
numbers are supplied here: the first just returns whatever value the
OS gets. The second is a psuedo-random number generator that returns
random numbers uniformly distributed over the interval [0.0 .. 1.0]
people
contains the "business" class (nothing related to flying in an airplane).
A large part of this class focuses on reading and writing a textual
representation of the business, which can be put onto a web page, a file,
or into a database
os
contains subroutines related to a computer process (aka, "program"):
get the ID of a process; terminate a process; wait for a process
servers
contains 2 classes: "gateway session" (gateway_session_o) class
provides support for web servers and user sessions with them;
"server-mover" (server_mover_o) is an 'internal' class for
supporting servers
is
www
support code for processing HTML in CGI programs
Layer 11
geo
contains global-level functions for obtaining data relating to Earth
geography (from a human point of view). This includes functions such as
zgeo_iscountry_valid(), zgeo_city_info(),
zgeo_country_info(), and zgeo_postal_info().
people
contains "business textstream" class (business_textstream_o),
for processing a list of businesses (eg, put into a file);
a "job" class (job_o), relating to the person-to-business link;
and the "worker" class (worker_o). This rather Marxian-sounding
name is used to describe a person's relationship to a business.
"employee" would be incorrect, as a person can be a contractor, partner,
owner, or otherwise not an employee and still work for the business.
Note that a person can have more than 1 job, and a business can have
more than 1 worker, so the business class does not "own" the worker class
servers
all the support classes at lower layers finally culminate into the server
class (server_o). With this object, you have lots of plumbing to
create a server that will patiently wait for incoming messages and process
them according to your specifications
Layer 12
servers
contains the "executive monitor server" class
(Executive_Monitor_Server_o), which is a special type of server.
it monitors, shuts down, and starts other servers
www
contains the class "CGI_webclient_server_o", which kicks off a CGI
program under a web server
|
