Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / ZROUTINE.ZIP / ZROUTINE.TXT < prev

Wrap

Text File | 1989-01-14 | 32.1 KB | 887 lines

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