category-group: quickdirt
layer(s): 0, 1, 2 header file(s): z_menuloop.h synopsis.
Various "quick & dirty" solutions are lumped into this group. During the evolution of the Z Directory, objects and subroutines that were needed to help a program "get the job done" were created, and if those components could not be categorized into a group that served an obvious task (in the computer science domain), it may have ended up here, as a "quick & dirty" to some problem. This group is similar to "etc" in that it is an agglomoration of different items, but it has turned into a framework for command-line driven applications. It includes subroutines for getting input from the console. classes in this group: rundriver_o, testdriver_o, menuloop_o, progconf_o function groups: layer 00 functions group description.
The "driver" series (rundriver and testdriver) provide a standardized framework for non-GUI (ie, command-line) programs. both objects parse the command line and set variables to indicate what the user wants the program to do. the testdriver_o class is a superset of the rundriver_o class (and is derived from it). Rundriver provides for checking if the user is reqeuesting help, setting the program's overall "volume" level, checking and setting database parameters, and a few other things. Testdriver adds the options of running in batch mode (ie to do a batch processing run); run in "interactive" mode, where the user is presented with a menu of choices for, gets input via command-line, and runs the task corresponding to the menu selection; and validation - the program does a test of an object (and/or possibly a group of functions, or multiple objects). The "test" version differs from the "run" version as it it is oriented for "test" programs. Layer 0 subroutines consist of a very few functions, such as z_quick_popup_message() - this function displays a windows-based popup message, and whether it works is highly dependent on the operating system; or z_wants_help(), which tells if the user is reqesting help information. From the rundriver_o and testdriver_o classes, a set ofcommand-line parameters with standardized, fixed meanings has evolved:
| argument | variable | notes |
|---|---|---|
| -h | -? | /? | help (brief summary) | |
| -help | help (long version, with more detail) | |
| -fullhelp | maximum help information - this indicates the user is very confused. Dump all the help info available. | |
| -V, -version | show version info | |
| -i, -interactive | run in 'interactive' mode | |
| -batch, -auto | run in 'batch' mode | |
| -kbd | -stdin | allow console input | |
| -vol | -volume | [n] | set volume level (n in [0..100]) |
| -nonstop | run an operation to its end, even if an error occured. This is intended for batch jobs and validation. | |
| -abort_onerr, -stop_onerr | stop processing an operation if an error occured. This is intended for batch jobs and validation. These keywords are the converse of -nonstop. | |
| -database | -db | [name] | set database name |
| -server | [name] | set database server |
| -host | [name] | set database host name |
| testdriver_o class command-line arguments | ||
| -e | run validation test(s). This is a self-test / unit-test, which outputs a terse, 1-line result message to the console (Microsoft: "command") window. This message announces whether the test passed, failed, or could not be done. . There are various reasons why a test might not be able to be performed. This is discussed below. | |
| -pause, -endpause | pause for user input after running a validation test. This allows the person running the validation test to review the output from the test. To let the program exit, type anything (at least 1 character) and press carriage-return. | |
"Volume" is intended to be used for debugging programs. The Z Directory standard is to use an integer number from 0 to 100. A higher number automatically includes any messges set at lower numbers. So, if volume is set at 70, messages at volume level 10, 20, or 50 will be displayed. Here are some guidelines for setting level control:
05 - show panics, program failures 10 -show errors only 20 - very light messaging: errors, and top-level program events 30 - show errors and severe warning messages 40 - show all warnings 50 - show errors, warnings, and other messages 60 - more messages 70 - heavy message tracing. Show 1 data within outer loops, terse format 80 - very deep message tracing. All data in nested loops is dumped. 90 - show massive dumps of all message types. For heavy-duty debugging. 100 - show absolutely everything. This is targeted for serious debugging or emergency repairs.For doing validation of functionality of components (functions and classes - intended to be performed by the testdriver class ), the protocol for testing each component is to run a program that automatically performs various tests of the unit. The exit code of the program determines the overall [pass/fail] result. The values of these exit codes are:
| value | meaning | description |
|---|---|---|
| 0 | test passed | all features of the component that were tested passed. |
| 1 | test failed | at least 1 test of the component failed. |
| 2 | validation has not been implemented | Vettrasoft programmers have not yet got around to writing code to test the object. |
| 3 | validation cannot be implemented | no automatic testing is available for the component. This is typically because there is no way to programmatically check the correctness of an operation. For example, with the 'barecomputer' or 'baredisk' class, there is no way to automatically check if the name of the computer is correct, or that the amount of memory or disk space is correct. The user may be able to confirm these things, but these tests must be able to run fully automated. |
| 4 | a configuration problem exists | Something prevents the test from running. This often applies to database-type tests; perhaps the database is down, or has not been installed. |
| 5 | dry mode | Actual validation is not performed if the program is in "dry mode". |
z_quick_popup_message() is currently only available on Microsoft-type operating systems.