ZRoutine Documentation January 14, 1989
Version 1.1 Page 1



_________________________________________________________________________

Introduction to ZROUTINE
_________________________________________________________________________
There is a Table of Contents at the back of this document!

ZRoutines are a collection of Turbo Pascal routines I find priceless
in coding my programs. I used to code in Quick Basic and became
dependent on some of its procedures and function. I have written them
as Pascal units.

To make sure that there is no confusion, all of the units in this
collection begin with the letter Z.

The author of these routines is Bob Zimmerman. I have gotten many
ideas from other public domain software and from other books and
manuals. I am sure there are other routines out there.

I am taking pride in this documentation and support. All requests
should be addressed to:


Bob Zimmerman
CompuServ 72371,1700

or

Bob Zimmerman
Sysop: The Mainframe BBS
2400/1200/300 8N1
24 Hours
(312) 364-0425 after Nov 1989 the area code is 708
(708) 364-0425...

ZRoutine Documentation January 14, 1989
Version 1.1 Page 2



_________________________________________________________________________

Printing this document
_________________________________________________________________________

This document may be printed by copying it to the printer using the
dos command:

COPY ZROUTINE.TXT PRN

The file is formatted to print on 10 x 8 inch paper. The reason I am
not using 11 inch formatting when creating this document, is so it
will print on a laser printer correctly (some only support 60 lines
per page.

Also, to make sure it will print on all printers, there is no bolding
or any other fancy font. I use the underscore chars to form the
heading lines and the form feed character to eject to a new page.

Hard copies of this document may be requested from the author. A
charge will be requested depending on the quality of the printout you
request (laser versus dot matrix...).

ZRoutine Documentation January 14, 1989
Version 1.1 Page 3



_________________________________________________________________________

ZBeep - Sound a beep "x" number of times
_________________________________________________________________________
Procedure ZBeep (Number_Of_Times : integer);

This routine will sound the speaker the number of times specified. I
have had alot of trouble remembering the exact pitch etc... used by
most utils. Once I found it, I created this module. For example...

Example:

(* To sound a single beep *)

ZBeep (1);

(* To sound 10 beeps *)

ZBeep (10);

ZRoutine Documentation January 14, 1989
Version 1.1 Page 4




_________________________________________________________________________

ZCmd - Global string variable
_________________________________________________________________________
Var ZCmd : String;

This a variable that is created at the beginning of every program. It
will contain the entire command line, each parameter being separated
by a single space.

Normally, in Turbo Pascal, there is no one parameter containing the
entire command line (for printing etc...). This one is it.


Example:

PROGRAM PrntCmd;

(* This program echos the command line back to the screen
in order to demonstrate the ZCmd string. Execute this
program with several different command lines to see the
spaces squashed out etc... *)

begin
Writeln(ZCmd);
end.
ZRoutine Documentation January 14, 1989
Version 1.1 Page 5



_________________________________________________________________________

ZCmdInt - returns a command line integer Function ZCmdInt (A_String :
string ) : integer;

This function is exactly like the ZCmdStr, except it returns an
integer. For example, is a /p parm is used to specify page length, you
could use this function to retrieve it...


Example:

THECMD /p60


The above command line would generate:

ZCmdInt('/p') returns 60


Notes:

If the user specifies alpha data, or no data, this function returns 0.
ZRoutine Documentation January 14, 1989
Version 1.1 Page 6



_________________________________________________________________________

ZCmdKeyWord - Checks for keyword on command line Function ZCmdKeyWord
( A_String : string ) : boolean

This function either returns True or Flase depending on whether or not
the passed "keyword" was specified on the dos command line.


Example:

THECMD c:\autoexec.bat /move save

if the above is the command line entered at the dos prompt, then the
following is true:


ZCmdKeyWord('/move') is true
ZCmdKeyWord('save') is true
ZCmdKeyWord('move') is false
ZRoutine Documentation January 14, 1989
Version 1.1 Page 7



_________________________________________________________________________

ZCmdPos - Get the positional parameter
_________________________________________________________________________
Function ZCmdPos (The_Pos : Word) : String;

This function returns the positional parameter on the command line.
Here is an explanation of its processing.

Starting with the first command line parameter, it checks if the first
byte is a slash (/). If it is, it skips that parm. If it is not, this
is considered a "positional" parameter. You specify which positional
parameter you want the function to be returned.


Example:

The dos command line looks like this...

THECOMMAND /r bob zimmerman /q /d whatever


Using the above command line... the following is true:

ZCmdPos(1) is equal to "bob"
ZCmdPos(2) is equal to "zimmerman"
ZCmdPos(3) is equal to "whatever"
ZCmdPos(4...) is equal to "" (nothing)


Notes:

If there are no positional parameters, then a string of length 0 is
returned. ZCmdPos(0) or ZCmdPos(-1) yields unpredictable results...
ZRoutine Documentation January 14, 1989
Version 1.1 Page 8



_________________________________________________________________________

ZCmdStr - return command line parameter
_________________________________________________________________________
Function ZCmdStr (A_String : string) : string;

This function returns the value for a command line parameter. You are
able to misuse this command if you don't understand its intention. If
your utility can receive a path parameter in the form of /pc:\, where
the /p is the "key" and the c:\ is the value, then the ZCmdStr would
look like this:


Example:

(* find out the value of the /p specified on the command line *)
Value := ZCmdStr('/p');


Notes:

This function works regardless of case. If the command line contains
just the key (/p in our example), or the key (/p) is not specified at
all, the function returns a string of length 0.
ZRoutine Documentation January 14, 1989
Version 1.1 Page 9



_________________________________________________________________________

ZColor - Set Text color Procedure ZColor (Foreground, Background :
integer);

The real purpose is too make pascal a bit easier for Basic
programmers. Instead of using the TextColor and BackColor procedures,
you may specify both in one statement...


Example:

(* set color to yellow on blue background *)
ZColor (14,1);

ZRoutine Documentation January 14, 1989
Version 1.1 Page 10



_________________________________________________________________________

ZCsr Procedures - modify Cursor Attributes
_________________________________________________________________________
The following procedures have no parameters. They modify your cursor
display attributes as described:

ZCsrNone; turns off the cursor from being displayed.
ZCsrBlock; makes the cursor a full block cursor.
ZCsrNormal; makes the cursor a normal underscore type.
ZCsrHalf; makes the cursor half of a block cursor.

ZCsrSize(x,y); allows you to explicitly code the scan values for
the cursor.
ZRoutine Documentation January 14, 1989
Version 1.1 Page 11



_________________________________________________________________________

ZLPadInt - Generate leading zeros
_________________________________________________________________________
Function ZLPadInt (TheVal, NumOfBytes : Integer) : string;

Many times, I would like to print an integer with leading zeros. By
default, leading zeros are stripped. Even using the formatting on the
Writeln command, the numbers are padded with spaces not zeros.

This function forces numbers to be printed with leading zeros.


Example:

(* I want to print numbers 1 to 100 aligned with leading zeros... *)

var
x : integer;

begin
for x := 1 to 100 do
Writeln( ZLPadInt (x, 3) );
end;


"x" is the number 1 to 100 (the for statement increments it)...
"3" specifies to pad it to 3 digits... Output looks like:

001
002
003
..
..
010
011
..
..
100

ZRoutine Documentation January 14, 1989
Version 1.1 Page 12



_________________________________________________________________________

ZInput - Formatted Input Routine
_________________________________________________________________________
Procedure ZInput;

This routine is a full screen formatted input routine. By filling in
the arrays described below, you tell the routine where fields are on
the screen. Then you invoke the ZInput Procedure. ZInput allows the
user to use page down and up to get to the 1st and last field,
tabbing, the HOME and END keys, CTL-END and more. The user is in
control until any key that takes a 2 byte scan code is pressed. For
example, the PFkeys, CTL- combinations etc... Also, pressing ENTER on
the last field, or the ESC key exits the procedure.

All data is optionally validated...
The following describes the variables (global) used when running
ZINPUT!:

ZIRow[1..25] Specify the row the field is on.
Use an index of 1 thru 25 for which field.
In other words, you can define up to 25 fields.

ZICol[1..25] Specify the column the field starts in.
Use an index of 1 thru 25 for which field we are
on.

ZILen[1..25] Specifies the length of each field.

ZIData[1..25] Specifies the data. If you set this prior to
invoking Zinput, the data is displayed to the user
for modification. After Zinput, the data the user
entered is returned to the program in this array.

ZIInvalid[1..25]
This array is used for editing. If the user is
allowed to enter any data in the field, leave the
field null (ZIInvalid[1] := '')...

If the user is only allowed to enter certain
chars, for example Numeric data, then set the
array entry to the list of valid chars. For
example, ZIInvalid[1]:='0123456789'.

ZINumOfFields contains the number of fields on the screen. You
must set this before you invoke ZInput.

ZIKeyPressed is returned with which key was pressed by the user
when returning control to your program.


continued on next page...
ZRoutine Documentation January 14, 1989
Version 1.1 Page 13




Example:

{ We want 2 data entry fields on the screen.
The first is a name field starting in column 5 row 10 for 20 bytes.
The next is a Yes or No prompt starting in column 5 row 11 for 1 byte.
This field should be intially set to Y.
}

ZIRow [1] := 10;
ZICol [1] := 5;
ZILen [1] := 20;
ZIData[1] := '';
ZIInvalid[1] := '';


ZIRow [2] := 11;
ZICol [2] := 5;
ZILen [2] := 1;
ZIData[2] := 'Y';
ZIInvalid[2] := 'YyNn';

ZINumOfFields := 2;

repeat

ZColor ( forground, background ); (* highlit color *)
ZInput;
ZColor ( forground, background ); (* normal color *)

if ZIKeyPressed := #27 then exit
ZBeep (1);

Until ZKeyPressed = #13;

ZRoutine Documentation January 14, 1989
Version 1.1 Page 14



_________________________________________________________________________

ZIOCheck - Did an IO error occur
_________________________________________________________________________
Function ZIOCheck : Boolean;

This function will run the ZIOResult procedure and sets itself to the
value of ZIOErr.

What this means to you, is that, this is an easy way to check the
status of IO errors after doing the I/O. See the example for more
info...


Example:

(* Open the file, if it does not exist, create the file *)

Assign (TheFile, 'temp.dat');

{$I-} Reset (TheFile); {$I+}

If ZIOCheck then ReWrite (TheFile);

{
In the above example, we are trying to first open an existing
file called TEMP.DAT. The $I- tells the compiler to let IO errors
fall back into the code since normally IO errors stop a program
immediately. The ZIOCheck will be set to true if an IO error
occurred. If it did, we assume it is because of the file not
existing and we CREATE (rewrite) the file. If this fails, the
system will generate a run time error.

See ZIOVerify for a cleaner implementation of this code!
}

ZRoutine Documentation January 14, 1989
Version 1.1 Page 15



_________________________________________________________________________

ZIOErr - Global variable var ZIOErr : Boolean;

This variable is used by the routines ZIOCheck, ZIOVerify and
ZIOResult, documented in this manual.

After ZIOResult, which is used by the other ZIO routines, ZIOErr is
set to true or false depending on whether an IO Error occurred. If an
IO error occurred, ZIOErr will be set to true.


ZRoutine Documentation January 14, 1989
Version 1.1 Page 16



_________________________________________________________________________

ZIOResult - Check IOResult
_________________________________________________________________________
Procedure ZIOResult(var x : integer; var msg : string);

This procedure analyzes IOResult (built into pascal) and determines if
the last IO generated an error. If it did, the error number is placed
in the integer being passed, ZIOErr is set to true and "msg" will
contain the reason the error occurred.


Example:

{$I-}
Rewrite (thefile);
{$I+}

ZIOResult (errnum, errmsg);

if ZioErr then begin
Writeln('An io error has occurred');
Writeln('Error number: ', errnum);
Writeln('Error message: ', errmsg);
ZBeep(2);
halt(1);
end;

ZRoutine Documentation January 14, 1989
Version 1.1 Page 17



_________________________________________________________________________

ZIOVerify - Verify the previous IO worked
_________________________________________________________________________
Procedure ZIOVerify;

This procedure will run ZIOResult. If ZIOErr is equal to true, meaning
an IO error occurred, then the alarm is sounded and 3 lines of
diagnostics are printed.

These messages are clearer then the simple "run time error" issued by
Pascal. They will explain why the io error occurred (e.g. Invalid
path, file not found etc...)


Example:

(* Open the file, if it does not exist, create the file *)

Assign (TheFile, 'temp.dat');

{$I-} Reset (TheFile); {$I+}

If ZIOCheck then
begin
{$I-} ReWrite (TheFile); {I+}
ZIOVerify;
end;


{
See the example under ZIOCheck for a full explanation of this
example. The new line ZIOVerify will verify the rewrite works. If
it does not, a formatted error message is displayed and the
program is halted.

}
ZRoutine Documentation January 14, 1989
Version 1.1 Page 18



_________________________________________________________________________

ZLTrim - Trim leading spaces
_________________________________________________________________________
Function ZLTrim (A_STring : string) : string;

Returns the string without any leading spaces.


XYZ := ZLTrim(' Bob');


XYZ will be equal to "Bob" without the leading spaces!
ZRoutine Documentation January 14, 1989
Version 1.1 Page 19



_________________________________________________________________________

ZMakeWindow - Generate a window
_________________________________________________________________________
Procedure ZMakeWindow (LeftColumn, TopRow, RightColumn, BottomRow,
: integer;
Foreground, Background : byte;
Windowtype : integer;);


This procedure is still under development but works fine. You specify
the dimensions of the box you want drawn. Specify the foreground and
background color, as well as a border type (windowtype). Currently,
window type must be 1 or 2.


Example:


ZMakeWindow (2,2,79,24,14,1,1);

The above draws a box around your entire screen. (note you must leave
a byte around the edge for the border.

When this is cleaned up, it will support growing boxes, more borders,
and support full 1,1,80,24... dimensions....

p.s. ZMakeWindowG uses the same operands but draws a window a bit
different!
ZRoutine Documentation January 14, 1989
Version 1.1 Page 20



_________________________________________________________________________

ZPad - Pad a string to a specified length Function ZPad (A_string,
Pad_string : string; TotalLength: Integer) : string;

This function will pad a string to the length of TotalLength.


Example:

(* Pad the heading with dashes across the page *)

Heading := ZPad('Zroutine documentation','-',80);

Will produce

Zroutine documentation-------------------------------------------
thru column 80.
ZRoutine Documentation January 14, 1989
Version 1.1 Page 21



_________________________________________________________________________

ZPress_Any_Key_To_Continue ;
_________________________________________________________________________
Procedure ZPress_Any_Key_To_Continue ;

This procedure writes the line Press any key to continue and waits for
the user to do so. There are three "features" built in.

First, after the user presses enter, the line with Press Any Key To
Continue is erased and the cursor is placed at the first byte of the
line. This means the line is usable, not scrolled up.

Second, a ZBEEP (2) is executed (see ZBeep in this doc). This may be
silenced with the ZSilent boolean function (also in this doc).

Third, if the user presses ESC, the program is stopped and control
returns to the system.

Example:

(* Silence the beeps *)
ZSilent := False;
(* Prompt the user to press enter *)
ZPress_Any_Key_To_Continue;


ZRoutine Documentation January 14, 1989
Version 1.1 Page 22



_________________________________________________________________________

ZRight - Select the rightmost characters
_________________________________________________________________________
Function ZRight (A_String : string; A_Word : Word) : string;

This function returns the right characters of a string.


Example:

XYZ := ZRight('Bob', 2);

XYZ is now equal to "ob".


XYZ := ZRight(abc, 1);

XYZ is now equal to the last byte of abc...


Notes:

If ZRight is told to select more than the length of the string, for
example, you request the 5 most right bytes of a 2 byte string, only
the 2 bytes are returned (equivalent to a simple assignment
statement).

ZRoutine Documentation January 14, 1989
Version 1.1 Page 23



_________________________________________________________________________

ZShell - Shell to dos
_________________________________________________________________________
Procedure ZShell(TheCommand : string);

This procedure shells to dos and invokes the specified command. To
shell to dos until the user specifies EXIT, use a null command
string...


Example:

ZShell ('');

Shells to dos until the user presses exit.

ZShell ('Dir *.*');

Shells to dos, issues the dir command and returns immediately.


Notes:

Be sure to use the compiler directive $M to set the max heap size to a
low value. The default is your program uses all memory. Override this
by specifying a minimal Heap amount.
ZRoutine Documentation January 14, 1989
Version 1.1 Page 24



_________________________________________________________________________

ZSilent - Global boolean variable
_________________________________________________________________________
Var ZSilent : Boolean;

This is a variable created and initialized to TRUE. There are many
functions within Zroutines that sound the alarm. If ZSilent is set to
FALSE, these functions will not sound the alarm.



Example:

(* The following line turns noise off *)
ZSilent := False;

(* The following line turns noise back on *)
ZSilent := True;

ZRoutine Documentation January 14, 1989
Version 1.1 Page 25



_________________________________________________________________________

ZStr - Returns string type of integers
_________________________________________________________________________
Function ZSTR (A_number: integer) : string;

This function is the compliment to the STR procedure.


Example:


TheString := ZStr(3);


ZRoutine Documentation January 14, 1989
Version 1.1 Page 26



_________________________________________________________________________

ZString - Generate a string of chars Function ZString (A_String :
string; A_Num : Word) : string;

This function returns a string by taking the string passed and
concatenating it to itself the A_Num of times specified.


Example:

XYZ := ZString('-',50);

will set XYZ to 50 dashes...

XYZ := ZString('abc',100);
is an illegal function and would generate run time errors or
unpredictable results. The reason is stringing abcabcabc 100 times
creates a string longer than 255 bytes. In pascal, a string may not
exceed 255 bytes!
ZRoutine Documentation January 14, 1989
Version 1.1 Page 27



_________________________________________________________________________

ZUCASE - Set a string to upper case
_________________________________________________________________________
Function ZUcase (A_String : string) : string;

The Pascal UPCASE function only works on "char" type data. This means
it only works on one byte at a time. Almost every time I have to set
some data to upper case, I must process a string of several bytes (not
just a single byte). ZUcase processes an entire string just like
UPCASE...


Examples:


(* Set the chars xyz to upper case *)
NewString := ZUcase('xyz');

(* Set the value of Name to upper case *)
NewString := ZUcase(Name);

(* Using ZCmd from these routines, set the command line to
upper case *)

ZCmd := ZUcase(ZCmd);
ZRoutine Documentation January 14, 1989
Version 1.1 Page 28



_________________________________________________________________________

ZWrite - Write a string to a screen area
_________________________________________________________________________
Procedure ZWrite (x,y : integer ; A_String);

Writes the given string at the x,y co-ordinates.


Example:

ZWrite (24,1,'This is the bottom of the screen');

Will generate that line at row 24, column 1.






Introduction...............................................1
Printing this document.....................................2
ZBeep
- Sound a beep "x" number of times.....................3
ZCmd
- Global string variable...............................4
ZCmdInt
- returns a command line integer.......................5
ZCmdKeyWord
- Checks for keyword on command line...................6
ZCmdPos
- Get the positional parameter.........................7
ZCmdStr
- return command line parameter........................8
ZColor
- Set Text color.......................................9
ZCsr
Procedures - modify Cursor Attributes
ZCsrNone..............................................10
ZCsrBlock.............................................10
ZCsrNormal............................................10
ZCsrHalf..............................................10
ZCsrSize(x,y).........................................10
ZLPadInt
- Generate leading zeros..............................11
ZInput
- Formatted Input Routine.............................12
ZIO - I/O Error routines
ZIOCheck - Did an IO error occur......................14
ZIOErr - Global variable..............................15
ZIOResult - Check IOResult............................16
ZIOVerify - Verify the previous IO worked.............17
ZLTrim
- Trim leading spaces.................................18
ZMakeWindow
- Generate a window...................................19
ZPad
- Pad a string to a specified length..................20
ZPress_Any_Key_To_Continue................................21
ZRight
- Select the rightmost characters.....................22
ZShell
- Shell to dos........................................23
ZSilent
- Global boolean variable.............................24
ZStr
- Returns string type of integers.....................25
ZString
- Generate a string of chars..........................26
ZUCASE
- Set a string to upper case..........................27
ZWrite
- Write a string to a screen area.....................28