category-group: quickdirt
layer: 0
header file(s): z_func.h
libraries: libz00.lib

synopsis.
This group contains only two functions: z_quick_popup_message() and z_wants_help(). The former displays a pop-up message in a window. This function doesn't really fit in to any logical abstraction - it should be part of a window system group, and probably at a much higher layer. It [currently] works only in Microsoft operating systems. However, it is such a handy item that we cannot ignore it. A "quick and dirty" place is truly where it belongs. The latter, z_wants_help(), is used for determining if there is a "desire for help" to be found in the command-line -

[C] functions (aka subroutines):

z_quick_popup_message()
SIGNATURE: int z_quick_popup_message (const char *msg, const char *title = NULL, boolean incl_syserr = FALSE, boolean do_leave = FALSE, int exit_code = 0, int *pie = NULL)
PARAMETERS
  • msg: the message to display.
  • title: the pop-up window's title text. if set to NULL, the title will be "ERROR".
  • incl_syserr: a flag. Defaults to FALSE. If set to TRUE, the message ("msg") will be concatenated with a [non-modifyable] error message. The text of the error message will be, if an error occurred:
    "%s failed with error %d: %s"
    Where the 1st '%s' is the text of paramter "msg", '%d' is the integer value of the error, and the 2nd '%s' is the OS-supplied text corresponding to the error.
    If no error occurred from the last system call, the message will have this format:
    "%s: no error (%s)"
    the 1st '%s' is that of "msg", and the 2nd '%s' is the OS-supplied text corresponding to no errors.
  • do_leave: if set to TRUE, this subroutine will exit. The exit code will be that of the value of the parameter exit_code.
  • pie: error indicator [output] flag value. This is currently always set to 0.
DESCRIPTION:
This function ("subroutine") provides a simple 'back-door' way to pop up a message, such as a warning or error message, in a Microsoft OS (running a window system by default - it won't work under pure MS-DOS). several parameters are provided to control style and control-flow behaviour, most with default values to make things easier. if incl_syserr is set [to TRUE], the last error will be analyzed. That is, any error created by the last OS system call will printed out. you can [optionally] exit out of the program by setting the exit_code variable to TRUE. The pop-up window will have a simple "OK" button, so the user can dismiss it after reading.
RETURNS: 0 (always - if it returns at all)
 

 

z_wants_help()
SIGNATURE: boolean z_wants_help (int argc, char *argv[], boolean &heavy, int *pi = NULL)
DESCRIPTION:
this function is intended to interact with rundriver_o and testdriver_o. It tells if there is a "-h", "-help", or "-?" in the program's command line, and if so, returns TRUE.
RETURNS:
TRUE: "help parameter" found in argv[] list
FALSE: no indication of a "help parameter" found in argv[] list
TRAITS: this function is rarely used and may be deleted in the future. Please avoid using it.
 

z_wants_version()
SIGNATURE: boolean z_wants_version (int argc, char *argv[], int *pexi)
DESCRIPTION:
this function is intended to interact with rundriver_o and testdriver_o. It tells if there is a "-V" in the program's command line, and if so, returns TRUE.
RETURNS:
TRUE: "version parameter" (-V) found in argv[] list
FALSE: no "version parameter" (-V) found in argv[] list
TRAITS: this function is rarely used and may be deleted in the future. Please avoid using it.