Frequently Asked Questions
- What is the Z Directory?
- What organizations can benefit from the Z Directory?
- what are some of its characteristics?
- Why is the Z Directory only for c++?
- Is the Z Directory open source?
- Can it integrate with other libraries?
- Why is the Z Directory not a DLL?
- If the Z Directory is a bunch of static libraries,
why must I run an installer?
(aka, "I don't want to run a .exe on my computer")
- What run-time framework or Redistributable Package do I need to install?
- Is the Z Directory portable?
- Was the Z Directory made by Vettrasoft?
- How much learning is involved?
- I find many interesting header files with
no entries in the reference manual.
Where can I find info on them?
- Why do I find so many "junk attic" sections of code? Or 'obsoname()' calls?
- Will my code break after a new version?
- What are the advantages of using it?
- What is the downside of using it?
- I can write perfectly fine c++ programs without
the Z Directory -
what do you think of that?
- top 10 reasons for using the Z Directory.
The Z Directory is similar to Rogue Wave, STL, or MFC in that regard. It is entirely written in C++. It runs on Unix (Sun Solaris, HP-UX) and Microsoft (Win32) platforms (however, as of this writing - May 2012 - the unix versions have yet to be publicly released). It has a wider scope than most commercial software toolkits - libraries.
If you are not a programmer - that is, you are not familiar with say, how a compiler turns code into a program: maybe you are a businessman, or non-engineering manager of engineers, or somebody besides a person looking for help in writing his or her c++ program. If so, please start with the "really simple" guide (see side bar at left) to help you understand what the Z Directory is all about. This essay is less formal, a bit more rambling and opinionated, but nevertheless a good place to start.
The spectum of applications where Z Dir can be used is broad:
- small, standalone programs (examples: an FTP program for MS Windows; a DVD burner - reader program; a word processor)
- web servers: since an HTML form can invoke most any program in the cgi-bin/ directory, they can run programs written in c++. The Z Directory has support functions for web servers.
- embedded programs, for devices: cell phones, PDAs, walkmans and iPods, bar code scanners, copy machines, even coffee makers and washing machines are Z Directory candidates. Microsoft provides the CE operating system - environment for devices, allowing c++ programs to be installed directlyinto them.
- an in-house, custom-coded system: an enterprise may develop its own infrastructure for data processing. Examples include accounting, POS, medical imaging, or broadband messaging and communications.
Thare are many, many examples across the board - whether it be a software business, or some other business that requires software written for it. Even hardware manufacturers need it, such as makers of copy machines or dishwashers. Most appliances and office equipment needs embedded software to run the devices - they too can benefit from the Z Directory.
The important (and limiting) criteria is that the software being developed is written in C++. Say there's a start-up business in Bethesda, MD, that does credit card payment systems, and their system is written in C#. They would be locked out of the benefits of the Z Directory - you can't [in any practical means] link C# code with C++ code.
The versatile Z Directory can accomodate low-tech or high-tech. If you're a newbie to software development, and want to build something in a hurry, you may want to slap together the Z Directory's more powerful components and throw a Microsoft Winows GUI on top of the program. Or perhaps you have a complicated multi-threaded operating system - there are plenty of Z Directory objects and subroutines to aid you, too.
In the case of containers like linked lists and strings, the interface forces you to think of the concept instead of implementation: differences in how you access elements depend on whether the collection is a list, a set, or an ordered list or set, or stack, etc. Whether the collection is done via array, linked list, or B-tree often makes no difference and hence access to items in each of these implementations has the same interface. Furthermore, you can specify the implementation if you wish - usually for performance issues. The bottom line is to say that the Z Directory provides things like linked lists and arrays is a deceptively simple statement. Underneath this apparent simplicity lies a sophisticated system.
If you study the header (include) files, you may notice that the structure is always the same - first a big long comment block, then #includes, followed by #defines, global variables, and function declarations. Ordering and style is uniform to almost a military precision. Subroutine names are generally longer than most other [cryptic] software, but not so long that the names occupy too much space on a line. Underscores are used liberally, and names are almost entirely in lower case - reflecting the Z Directory's unix roots. Also, function types, names, and parameter signitures are usually lined up. There are no tabs. Indentation is 4 spaces. Love it or hate it, this dull McDonald's-like approach means that you get the same uniform quality. 'Quality' in this case means readability, so you can focus on the contents of what's written, rather than wrestle with having to shift gears coping with various styles. Of course, you may disklike or even abhor its style. But, the style chosen has evolved over many years, with many decisions over time going into what style of code writing is optimal. For instance, the readson tabs were abandoned, was that some people set tab stops away from the historical default of 8 to 4, or perhaps some oddball value such as 3, 7, or 29. This meant that if tabs were used, the code would line up different depending on the user. So eventually tabs were discarded altogether. Lines rarely run past the 80th column. This comes from computers' historical origins of 80-character wide CRTs. Of course most editors nowadays can expand their widths to any value up to the screen size. The downsides to that is that expansion eats up screen real-estate, and some editors may be able to wrap text while others can't. Some who use this auto-wrap feature end up making lines that are hundreds of characters wide, and if that file is edited by someone else who doesn't use auto-wrap, the text they need to read could scroll right endlessly, resulting in it being horribly annoying to read. As to why a column wider than 80 was not chosen - historically it's been 80 (a good width), and that has become a standard of sorts.
"Open source": is not always a cure-all solution for software. By making public all source code, this can result in perpetual debate and users all arguing for their own wants and desired directions. It also results in many people spending a lot of time reading and studying code detaile. On the other hand, a completely closed system puts a damper on valuable feedback and promotion of good ideas. Vettrasoft opts for the middle ground. We allow users to learn the interfaces (and in fact, it is necessary in order to use the system) and encourage feedback and ideas. But the bulk of the implementation stays internal. At the end of the day, Vettrasoft decides what to add and what to modify. There are arguments to this approach, both pro and con. An analogy is which model do you prefer to get a job done: appoint a commander to lead the battle, or a comittee. Vettrasoft is comitted to working closely and in full co-operation with the end user. Feedback is regarded as vital tool to help guide Vettrasoft in developing future code that the user community needs. We prefer to think of the system as a series of black boxes with simple interfaces (the part you see), but best to hide the gory implementation details.
Here you see a fully functional (and useful) program that uses both the Z Directory and "Chilkat" (an alternative object library). As this picture illustrates, you can mix and match Z Directory objects with other objects.
The introduction of DLLs and making it the de-facto output type, we believe was a mistake. On the usage side, the list of problems created by DLLs has been coined DLL Hell . On the programming side, making a DLL requires adding an export list and incorporating various strange keywords such as _stdcall or __declspec(dllexport) into the language. Real C++ does not have these keywords. The DLL is another trick to lock source code into the Microsoft domain. Microsoft has invested a lot to make you believe that the DLL is absolutely necessary, and the reasons why have been quoted religiously by many over the decades. The Z Directory grew up in a Unix environment, where static libraries are the norm. Although shared-object libraries (.so) exist, their usage is less common.
Computer memory has increased to the multi-gigabyte scale, so the extra memory loss incurred by duplicating a library into each program copy is minute. Over 90% of time, a single program using the Z Directory will run to completion on a given computer, or perhaps 5 such programs might be running concurretly - a GUI-based program, a server process, etc. The case of hundreds of the same program running simultaneously would occur usually in specialized environments on top-end computers with huge amounts of memory. Don't be afraid to use static libraries!
(This issue is discussed in the [Software] Basics page, in the section "Z Directory: Pluses and Minuses")
Since you link to a set of static libraries, there are no "frameworks", "packages", "redistributables", "service packs", or other such monstrosities. If you want to use a more modern version of the Z Directory, simply install it and [re]link your program(s) to it. Vettrasoft keeps things simple by rigid internal quality control. This lets you focus on your software, instead of keeping up (or playing catch-up) with the OS vendor's changes, whims, and politics.
Another example is that of running a sub-process. In unix environments, this would be called a 'child' process, done by exotically named OS API functions fork() and exec() ("exec" is actually a family of functions [execl(), execvp(), etc] - a different function, depending on how you want your "exec()" to behave). Now take the case of running the sub-program as a 'service'. Services exist in both unix and microsoft environments; however, the devil is in the details. Firstly, to install a program as a service on a unix box, this can only be done as root (the master administrator account). There are several implementation details between the Operating Systems - even between versions of the OS's. In early Microsoft variants, the service would have to be installed as a TSR ("Terminate and Stay Resident") - later Microsoft OS versions obviated this requirement.
We would very much want to have the Z Directory be 100% portable. The concept is that you can take a software program made on one OS, build it on a different OS [that the Z Directory is available on], and the program would run exactly the same on both (correction: at least the Z Directory part of it would). This seemingly simple concept is about as likely as the concept that you can transplant a person to another planet and have that planet be just like earth, with cars, houesee, cities, subdivisions, parking lots, and shopping malls. There are various approaches to the portability issue: making little programs that work like the originals in a new OS (cygwin, gnu, MKS); making a run-time system under the new OS that emulates the old OS (such as IBM's ILE environment for AS/400); or even providing the entire OS as a program that runs under the new OS. Each approach has its drawbacks. One consideration is to provid a subsystem that runs under a particular OS to provide functionality lacking in another OS. Once again, the Microsoft registry provides a basis to explain this: the Z Directory can install a subsystem that acts as a registry on unix (ie, linux, Solaris, AIX, HP-UX) systems. However, this propels the Z Directory away from simply a set of [static] objects found in a library file that one links to, and into the realm of a large run-time system (ie, SAP, Kenan-Arbor, Silverstream, Documentum, Siebel, etc). Vettrasoft is seriously considering this approach.
- binary-to-cleartext, base 64: Rene Nyffenegger and Bob Trower;
- binary-to-cleartext, uuencoding: Stephen Satchell (Satchell Evaluations) and Chuck Forsberg (Omen Technology); Mark G. Mendel (Network Systems Corporation) and the Regents of the University of California
- regular expressions: Henry Spencer
- encryption: Rob McCool and the Regents of the University of California for the "Cool Hash" code (coolhash_crypt_o)
- encryption: Bill Chambers and Bob Jenkins, for Chambers-Jenkins ("Chambers-Rantgen"?) encryption algorithm; Bruce Schneier, for Blowfish encryption; and Niyaz PK, for his implementation of RSA
One good way to quickly get up to speed is to look at source code that uses the Z Directory. You can download the sample projects (found here in this web site - click on samples). Also, many of the reference (man) pages contain detailed, readable explanations about the objects and functions.
- (a) there is some debate whether to include the object, or perhpas the way it is implemented needs substantial re-work;
- (b) Vettrasoft has not completed validating that the interfaces are in best possible shape, so that it is ready for public consumption;
- (c) the item has not gone (or passed) quality assurance (SQA) testing
In other cases, Vettrasoft simply hasn't completed the documentation. If the component has an entry in its group - say, in the dbag group, under the line "classes in this group" there is simple_dbag_o, list_dbag_o, array_dbag_o, rec_dbag_o, matrix_dbag_o, and HTI_dbag_o. Suppose (or perhaps it is so) that for HTI_dbag_o the documentation page indicates that the page is a stub - in that case, the object is in the system, but we haven't completed its documentation.
If the item is of interest to you, the best thing you can do is let us know (via the web-mailer) about it. We look at such requests in prioritizing our work.
We do evolve the names over time, and in order to make sure code does not break, we put the discarded names into "temporary holding zones". That is, we deprecate them. We also provide the z_obsoname() macro function to emit little warning messages, so we (and you) can ferret out deprecated functions and update them.
Vettrasoft really works at assigning names. We believe it's important, because that is what you will see most and become very familiar with over time. Software is not a chore at Vettrasoft - it's an art form.
Undocumented components are most at risk to such changes. These components exist and can be found via the header (.h, include) files. If the component has no corresponding entry in the reference manual , or its entry contains warnings about possible/future signiture changes, you should not use it unless you are prepared to modify its usage at some future point in time.
Unfortunately, Vettrasoft has no tool that one can apply to do a type of automatic source code change. This is currently an area of research, to find the best way to do this.
- data bags data bags provide an alternative to XML, with a rather more readable style;
- a simple o-o database methodology allows you to store and retrieve objects to an SQL-based database. The database used is independent of the interface. The database access methods include ODBC and ADO.
The Z Directory "protects" you from the environment. By using it, you can avoid using many system calls directly. This allows for code portability. For example, to get the time from the computer, in a Unix environment it involves invoking the system call time(), which returns the time in seconds. The variable type for that is time_t on Sun OS, solaris, HP-UX, and Free BSD unix flavors. For other Unix variants, the variable type is a long integer. This is followed by calls to localtime() and gettimeofday(). On the Microsoft side, if using Visual C++, you would call _localtime64(). If not using Visual C++, you can do a call using int86()..
This is all well and fine for those of you that want to show that you are software trivia knowledge-sponge queens. By now you probably see by now how much work is involved to handle all the cases set up by all the operating system vendors for this single problem. For those of you that are more interested in just getting the current time [/date] and getting on with the problem at hand, the Z Directory isolates this messy detail and simplifies it as so:
time_o t; t.now();Not only do you have protective walls between your code and the operating system, but other systems as well, such as databases and network transport protocols, and possibly some proprietary solutions that deal with specific areas in computer software. With the Z Directory, you work with one unified system, instead of pulling pieces of code from various vendors, then linking them all together.
Z Directory works with existing C [/C++] libraries.
Through namespacing, the Z Directory will not clash with other code you use, whether via header files or linkable object modules.
- Z Directory is cross-platform.
- The Z Directory acts as an insulator from problematic interfaces
provided by the environment (such as the operating system).
What this means, is that besides cross-platform portability, there may be operations that are overly complicated for the task at hand (consider all the nuances of using sockets to send a block of bytes across the wire); or a system call may be deficient (why is it strncpy() does not add a null terminator to your string?); or some committee may declare an interface function that you have employed a lot to be illegal (POSIX name changes).
When you encounter these things as an engineer, it is your responsibility to keep your programs functioning under the shifting sands of software. the Z Directory transfers this responsibility to Vettrasoft. It is our job to connect the interfaces we provide you with that of the Operating System (the "OS"), or to make sure they work with a new database or other tool. This frees you from a huge burden of learning, porting, and maintenance, allowing you to focus on the functionality you intended your software to provide.
- Z Directory is universal / multi-purpose / generic.
It is an art form that takes experience and smarts to design software that can be used in a variety of contexts. It is hard work to not bind systems together. Vettrasoft is proud of how well the Z Directory can be used in so many ways, whether you are building a console-based unix program or MFC in for Microsoft XP; using Informix, Oracle, or a custom database; passing messages with TLI, shared memory, sockets, or MQ Series.
- Z Directory is Y2K compliant.
This staetment may seem antiquated now, but it demonstrates a point. Since the 1980's, the Z Directory way of counting time has never taken shortcuts such as throwing away part of the data because the program can run without it for a while. The Z Directory takes a scientific view; time is simply time. it does not differentiate between time and date. A point in time is just that, down to the microsecond.
- Z Directory is mature.
the Z Directory started around 1985. The APIs have been refined over years. Internal versions have been released several times, before the Z Directory has ever been released to the public. What other vendor or major software toolkit can claim so much preparation time and effort into their product?
- Z Directory is here to stay.
Some systems have come and gone. the Z Directory is at the leading edge of computer technology and is being actively and continuously expanded. Years of pre-market preparation has created a solid, stable foundation. No line of code is allowed to be comprimised for lack of time, false deadlines, pleasing the boss, laziness or incompetence. If there is a way to improve on some bit of Z Directory software, it will be done. Yet, As powerful as it is, there are many many cool things planned on the horizon.
Although the Z Directory started out on unix-solaris, it currently runs on Microsoft platforms. As of spring 2011, ports to versions of unix: linux, and (free) BSD - are under development.
I don't like to be forced into that style.
ANSWER: We use a very specific style to enhance understanding and readability of software source code. The style does not detract from its implementation, functionality, or power. Vettrasoft is serious about its coding standards, and those used have been carefully thought out over decades. Knowing how the Z Directory code is written and organized makes it much easier to locate things.
One approach is to have very few rules for software coding style. This is akin to allowing a sentence can be written any way you like, instead of being forced to have a subject and predicate; or, that verbs can be written without regard to tense. Without standards, an extreme would be 2 alow dze rite to kree-ate ur oWN sPELZING rOOLZ.
- It's too complicated.
ANSWER: A lot of effort is made to to maintain the goals: simplicity, universality, functionality. Unfortunately, the introduction of any new system involves the time-and-effort investment of learning how to use it. We can steer you to many other libraries that you might think must be great because it looks complicated. It's a big system. Systems require learning. we have tried to standardize and simplify it as much as optimal. There are a lot of "get()" and "put()" functions across the board. Also, the Z Directory reuses itself to a high degree. You could say it is tightly wound.
The documentation, we hope, is simple and effective. Please write to Vettrasoft with any complaints or suggestions. As time progresses, problems will be solved. We are determined.
- It's too tightly wound. What this means is that, for any given component in the Z Directory, the component likely will use another Z Directory component. This can cause the user to chase one object after another to learn what's going on. The Z Directory uses itself heavily, so digging into any of it leads to other areas of the z directory. However, this is what O-O is all about. Oftentimes, to get a task done, there is the choice of using an existing object or writing low-level code with a lot of flow control (loops, if statements, etc). By opting for using the object, the system has less code - the z-directory re-uses itself; also, less redundancy and better insulation from operating system and environmental quirks.
- It should be organized by groups, such as sockets, containers,
Although it may seem nonsensical to organize the primary grouping by such
a mechanical item as layers, the decision to organize by layers has
proven to maintain the structural integrity of the system over time.
This program, how to organize the software, is akin to the
multiple-inheritance problem whan a thing is-a [this] and is-a [that],
and one must categorize the thing - which is correct?:
this/that/thing that/this/thingThis problem is more general than computer science - for instance, when an accountant organizes a hierarchal chart of accounts, and an expense can be categorized in more then one way, a decision how to group must be made. For instance, if the person / business has these expense accounts as part of the COA:
internet charges web hoster fees domain registration fees ISP feesand internet access via internet cafe is to be added, should it go under "internet charges"? Perhaps this is a rarely-used item that should be lumped into sundry or miscellaneous expenses. Or perhaps it should be added under ISP fees. Where to add it could be endlessly debated. To dive into the discussion about why we chose to group by layers is quite long, and hence, beyond the scope of this FAQ.
The Z Directory doesn't use STL [, boost, rogue wave, ... whatever, etc.]
ANSWER: There are a variety of reasons we can give you here. One big one is that the Z Directory predates many other libraries, including STL. One can argue that there is no need to re-create the wheel, but each wheel is different. We prefer ours.
it is non-standard.
What defines a standard? Any group of people say "plan X is the world
standard". Perhaps a product needs first to be approved by ANSI, or
ISO? the AMA? the FBI?
The z directory abstracts a wide range of topics in computer science and the 'real world' (math, accounting, e-commerce, time, etc). It provides a uniform programming conventions that cover a wide range of disciplines. There are not many other software libraries htat do it in a unified manner.
I don't want to be locked into a vendor.
ANSWER: You have no choice! If software is a war, then you must choose sides. For example - suppose you want a GUI application, but don't want to lock into a specific type of Window system. This might have been a due to a painful experience from the past. If you wrote Suntools code for your app's windows back in the mid 80's, all that code would eventually become obsolete. You probably would have switched to X Windows, but even so, you would have to choose from the different interfaces available (Motif became the dominant winner). But even X-Windows seems to have faded, overshadowed by Microsoft's window system API. If you had kept switching as new window systems evolved, you would have incurred huge costs (time and money) keeping up. An alternative could be to use software packages that offered 'generic' window programming. This would buffer your program from the native window system. However, you might encounter problems in pursuing this route:
- Which vendor to use?
- Would the chosen vendor's software work on all the platforms you want?
- You would be stuck with their methodology, nomenclature, bugs and other problems.
- The vendor might go out of business, stranding your code.
The Z Directory takes a monolithic approach, as opposed to you mixing and matching software components from different vendors in your application. This is the SAP approach: 1 vendor provides a framework for all your needs. It is a simpler solution than the mix-and-match approach, which leaves you by yourself to resolve any conflicts amongst the various subsystems. These problems can include inability to link the modules togehter; namespace conflicts; strange and unresolvable run-time errors (an uncaught exception thrown from deep inside a low-level library may result in perpetual crashes); certain components not being available for the compiler, IDE, and/or operating system version you are using; and other nagging issues.
I don't want to pay for it.
ANSWER: Agreed, all humans should be doing charity work, but we (like most humans) prefer to get something for the work we do. If you are too strapped to purchase it, please contact us to discuss a payment plan.
- Your code will mushroom with age. As you begin to realize that you want to add features similar to, but not quite exactly, as some part of your program, you will begin to copy sections of the code and paste them to new files, tweaking a few lines (Bellsouth: an offical policy they call 'blueboxing'). As you continue to tire of the program and take more and more shortcuts, your code will begin to lose structure and become progressively bloated. Finally, like a fat, weak old person, it will be time for your code to die - because you didn't create proper quality software in the first place.
- If the business grows, and they hire new people with their own opinions about what's the correct way to write source code (just like every season there is a new crop of weeds). Those people will either fail to learn the existing system, creating more code that duplicates some other part of the overall system, or they will hate having to use the database / component / add-on / OS you have imposed on them. They will secretly write code to avoid that, creating a nightmare of unmanageable subsystems. Better yet: you hired a group of contractors, they wrote some add-on code that seems to solve the immediate problem at hand, and now you are going through the [undocumented] source code trying to fix a new problem (think of a leaky plumbing system, the pipes are about to burst). You realize to your horror what incongrous, incoherent code they have dropped into your software system (and of course, they have been paid off and are long gone).
- Birds of a feather: a group of people gather that love some particular program, OS, databbase, or something, and hate the others. Maybe a bunch of Microserfs get together (like charged particles) and write a bunch of code that runs only on a Microsoft OS - or a bunch of unix-types hack together a system based on bash, awk, sed, nroff, /tmp directory, etc. Either way, the result runs only on the particular environment they have used and now they realize there are entire populations that don't use or care for their particular environment. Too late - they would have to start over. If any of these scenarios are familiar to you, you know what you need to do to Do The Right Thing. 'NuffSaid.
I can write perfectly fine c++ programs without the Z Directory - what do you think of that? (or, "I don't need no stinkin' Z Directory")
PREAMBLE: Vettrasoft invests a lot of time and effort into software architecture so that you don't have to. This involves planning and thinking about the future. You are absolutely allowed to not use the Z Directory; if that is your decision, you are hereby warned that one or more of the following events and effects will happen to the software you create:
- you want to write a program quickly. You're a math student, or a scientist on a quest. You need a computer to solve your equation. How much of your life will you divert to learning why srand() has an 's' in front of it? or the return type of an exception thrown up deep within some vendor's package?
- you hate a particular database or operating system . But you still want to write a program - the Z Directory can and does insulate you from such things.
- you hate porting . Eg, it works on Debian linux, now you want to make it work on Microsoft Vista; or vice-versa. Typically, a person becomes adept at one or the other system, rarely both. It's a big learning curve to move into foreign territory.
- the Z Directory has things found nowhere else .
Oh yes: some of the software components are found only here. Think of them as rare, exotic species. Some of the interfaces used in the Z Directory might exist in other packages, but are not widespread. You can readily find o-o libraries that have functions or objects named as 'socket-this' or 'socket-that', whereas the Z Directory approach is to label it as a 'message-transporter'. Objects such as the keyword processor or multi-cipher encryptor may exist somewhere else - we don't know of any (particularly with large commercial package software).
Frankly, the entire Z Directory concept is rather unique - there are not too many o-o software API libraries that cover a broad range of domains, integrated into a singular system.
- [candidate #1: why-I-use the Z Directory]
Send us an e-mail, your reason for using the Z Directory. Winning candidates will have their name posted here.
- [candidate #2: why I love the Z Directory]
Send us an e-mail, your best reasons(s) for using the Z Directory. We will evaluate all responses and put the winner's text in this slot.
- [candidate #3: a top reason for using the Z Directory]
- [candidate #4: Z Directory pro not con reason]
- [candidate #5: the ultimate (eg last word) pro-Z-Directory comment] Vettrasoft thanks everybody who uses our software. May you create great things, serve vast numbers of people, and make lots of money by using our software objects!