Power-Programmierung

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

/ Power-Programmierung / CD1.mdf / basic / library / pb / pbwiz10 / pbwiz.doc < prev next >

Wrap

Text File | 1991-12-03 | 35.6 KB | 871 lines

The PowerBASIC Wizard's Library =-----------------------------= Version 1.0 PBWIZ Copyright (c) 1991 Thomas G. Hanlin III This is PBWiz, a library of assembly language and BASIC routines for use with PowerBASIC version 2.0. Full source code is available with registration. The PBWiz collection is copyrighted and may be distributed only under the following conditions: 1) No fee of over $10.00 may be charged for distribution. This restriction applies only to physical copies and is not meant to prevent distribution by telecommunication services. 2) All PBWiz files must be distributed together in original, unaltered form. This includes BIBLIO.TXT, CATALOG.TXT, PBWIZ.DOC, PBWIZ.NEW, REGISTER.TXT, WHERE.BBS, and the two archives, INCLUDES and UNITS. 3) No files may be added to the PBWiz collection. This applies most specifically to the practice of adding BBS ads to archives, which I find seriously offensive. You use this library at your own risk. It has been tested by me on my own computer, but I will not assume any responsibility for any problems which PBWiz may cause you. If you do encounter a problem, please let me know about it, and I will do my best to verify and repair the error. It is expected that if you find PBWiz useful, you will register your copy. You may not use PBWiz routines in programs intended for sale unless you have registered. Registration entitles you to receive the latest version of PBWiz, complete with full source code in assembly language and BASIC. The assembly code is designed for the MASM 6.0 assembler and may require minor modifications if you wish to use it with OPTASM, TASM, or earlier versions of MASM. Warning: Use of PBWiz for more than 30 days without registering has been determined to cause fatal nose warts in penguins! It may also encourage the author to practice the tuba under your window at night. Table of Contents page 2 Overview and Legal Info .................................................. 1 Table of Contents ........................................................ 2 Archives ................................................................. 3 Dates and Times .......................................................... 5 Equipment Info ........................................................... 6 Extended Math ............................................................ 9 Graphics ................................................................ 12 Mouse Support ........................................................... 15 Strings ................................................................. 18 Credits ................................................................. 21 Archives page 3 When I started in the microcomputer industry, there were a variety of file archivers, all (more or less) compatible. They did not provide compression, which was relegated to another large selection of more-or-less compatible utilities. Then came SEA's ARC. It was very slow, but it did compression as well as archiving, and included CRC checks so you could know whether the files were intact. It swept the BBS scene in short order, becoming the new standard. A few other archivers competed on about a level footing, providing only minor variances on the ARC theme. Then SEA decided to sue one of the more successful competitors, Phil Katz (PKARC). The end result was the ZIP standard... but in the chaos resulting from the breaking of the ARC standard, many other archivers came into being: ARJ, LZH, PAK, ZOO, and so forth. PBWiz helps resolve the confusion by providing a single set of routines which allow you to view the contents of archives in any of the above-mentioned formats: ARC, ARJ, LZH, PAK, ZIP, or ZOO. Only archive directories are provided at this time. Other formats will also be added as they arise. If you have details on the format of an archive that you'd like me to add, please send them my way. I'll do what I can to get it into PBWiz. This unit requires the STRING unit (discussed later) as well. To use it in your program, you need to include both units: $INCLUDE "string.inc" ' (only if you need STRING in your programs) $INCLUDE "archives.inc" $LINK "stringa.obj" $LINK "stringb.pbu" $LINK "archives.pbu" Viewing archive directories is handled in roughly the same fashion as you might view a DOS file directory. This makes it possible to treat an archive and a subdirectory in a similar manner. When you're looking for the first file in an archive, use the FindFirstA function. You must specify the archive name and a file name. The archive name may include a drive and path specification, and does not need to have the archive extension. If you leave off the extension, FindFirstA will use the first archive it comes across that matches the rest of the specification. Note that the archive specification may not contain wildcards. In contrast, the search file name may not contain drive or path specs, but may contain wildcards. CALL FindFirstA (Archive$, Filename$, ErrCode%) Archives page 4 If there are no files to be found, or if the archive specification was bad, an error code will be returned. If there was no error, there may well be more files to be found. You can find each of them with FindNextA: CALL FindNextA (ErrCode%) Of course, just finding a matching file doesn't do you much good unless you can retrieve information about it. You can use any of the following routines to provide information about a matched file: Nam$ = GetNameA$ Dat$ = GetDateA$ Tim$ = GetTimeA$ CRC$ = GetCRCA$ StorageMethod$ = GetStoreA$ CALL GetSizeA (OriginalSize&, CurrentSize&) When you're done viewing an archive, be sure to close it: CALL CloseA Let's try an example. Given that you've already written the $INCLUDE and $LINK lines as specified on the previous page, you could see all of the files in an archive using a program like this: CALL FindFirstA (Archive$, "*.*", ErrCode%) DO UNTIL ErrCode% PRINT GetNameA$ CALL FindNextA (ErrCode%) LOOP CALL FCloseA This program fragment also assumes that you have set Archive$ to the name of an archive. It might be convenient to set it to the command line for testing purposes: Archive$ = UCASE$(LTRIM$(RTRIM$(COMMAND$))) Dates and Times page 5 This unit allows you to validate and compare dates. It also provides the day of the week, given the date. Dates may not be before the year 1900. Date strings may be in the form "01/01/91" or "01-01-1991" (the delimiter is not significant and years may be two or four digits; two-digit years will be assumed to be in the 20th century). To use the routines in this unit, include the following lines at the top of your program: $INCLUDE "timedate.inc" $LINK "timedate.pbu" Let's start off with date validation. It's often important to know if a date entered into your program is a valid date. IF GoodDate%(DateSt$) THEN PRINT "The date is valid." It can also be helpful to know on which day of the week a given date falls. Day$ = WeekDay$(DateSt$) There are many useful things you can accomplish by turning a date into a number which represents that date (or vice versa). This allows you to compare two dates, which is important if you want to sort by date; find out what the date will be in a given number of days, or what it was some number of days ago; find the number of days between two dates; display a calendar; and so forth. This is easy to do with PBWiz: DateNr& = Date2Num&(DateSt$) DateSt$ = Num2Date$(DateNr&) The DateNr& represents the number of days since January 1, 1900. This is less than 65,535 for dates that go up to around the year 2070 or so, so you may wish to store the dates in compressed two-byte form if your required range of dates is not that large: CrunchDate% = CVI(LEFT$(MKL$(DateNr&), 2)) This can be reversed simply: DateNr& = CVL(MKI$(CrunchDate%) + STRING$(2, 0)) Note that dates crunched this way are only useful for storage purposes, since the numbers greater than 32,767 are stored as negative numbers due to the signed integer format BASIC uses. You must uncompress them before doing any comparisons or date calculations. Still, at half the size, it can be worth the hassle to convert back and forth. Equipment Info page 6 The equipment unit gives you information about the computing environment. This includes both installed software and hardware. You can use the equipment information routines by including these lines in your program: $INCLUDE "equipmen.inc" $LINK "equipmen.obj" The first function allows you to determine if an "enhanced" keyboard (101-key) is installed. It may not be able to figure out what the keyboard is on some older not-quite-clone PCs, in which case it will take the safe way out and report that there is no enhanced keyboard. This function returns -1 if there is an enhanced keyboard present, 0 if not. Enhanced% = KbdType% Want to know the type of processor (CPU) being used? Can do! CPU% = Processor% The results will be reported as a number which can be decoded as follow: 0 NEC V20 1 8088 or 8086 2 80186 3 80286 4 80386 or 80486 If anyone knows how to differentiate between an 80386 and an 80486, please let me know. I've only seen one test which could do it, and it wasn't reliable. Maybe you'd like to check for a CD-ROM drive: Drives% = CDROM% This tells you how many logical drives exist, if there is a CD-ROM available. If not, it will return 0. Note that the CD-ROM installation check conflicts with the GRAPHICS.COM installation check for DOS 4.0, due to some screw-up at IBM or Microsoft. I'm not yet sure whether DOS 5.0 is similarly afflicted. The number of floppy drives installed is retrieved like this: Drives% = Floppies% Equipment Info page 7 Now, there may be up to four floppy drives in a system; however, the AT CMOS data area only directly supports two. This makes it easy to find out what kind of drives the first two are, but not the second two. Oh well, guess we'll have to settle for what we can get, right? CALL FloppyType (Drive1, Drive2) The results from FloppyType are returned as follows: 0 no drive 1 5 1/4" 360K 2 5 1/4" 1.2M 3 3 1/2" 720K 4 3 1/2" 1.44M Result codes of 5-7 are available, but not yet defined. One might guess that the 2.88M drive supported by DOS 5.0 will be drive type 5. Has anybody seen one of those puppies yet? New memory types sure have burgeoned over the years... expanded, extended, and now XMS. There are routines to check all of these: BaseExt& = AllExtMem& ' amount of extended memory actually installed NowExt& = GetExtM& ' amount of BIOS extended memory available CALL GetEMSm (TotalPages%, FreePages%) ' amount of expanded memory CALL GetXMSm (LargestFree&, TotalFree&) ' amount of XMS memory When you're dealing with extended memory, whether it be BIOS-type or using the XMS standard, the results are returned in kilobytes. Multiply 'em by 1024 to convert to bytes. When you're dealing with expanded memory (EMS), the results are in pages of 16,384 bytes. I might note, by the way, that Microsoft seems to have intentionally crippled the XMS standard. It can only support a maximum of 64 megabytes. This may seem like a lot now, but I can remember when my first PC (a Compaq portable) was the awe of the neighborhood with 384K RAM! A few years down the road, the artificial limitations of XMS are going to be a real nuisance. A few more routines to get the versions of the EMS and XMS drivers, if any: CALL GetEMSv (MajorV%, MinorV%) CALL GetXMSv (MajorV%, MinorV%) These return the major and minor version numbers as two separate integers. For example, EMS 4.0 would return major version 4, minor version 0. Equipment Info page 8 It's nice to know a little about the operating environment. With the below routines, you can find out what the DOS version is; what version of 4DOS, if any, is in use; and whether Microsoft Windows is running. CALL GetDOSv (MajorV%, MinorV%) CALL Get4DOSv (MajorV%, MinorV%) CALL WinCheck (MajorV%, MinorV%) These return results as major and minor version numbers, as discussed on the previous page. The Get4DOSv and WinCheck routines return zeroes if 4DOS and Windows, respectively, are not available. There are a couple of curious features of GetDOSv to keep in mind. If the version is 10 or higher, you're running in OS/2 compatibility mode. DOS version 10 is actually OS/2 1.0, version 20 is OS/2 2.0, and so on. Secondly, if you're using DOS 5.0, the version reported may not be 5.0-- DOS 5.0 can be told to reply with a lower version number to allow some older software (which checks for a specific DOS version) to run properly. One final routine that should be of some value is the one that allows you to find out what kind of display is available. It tells you the specific adapter and whether the display is color or monochrome. There is one case in which it can be confused, however-- if the adapter is CGA, the display is assumed to be color, since there is no way for the computer to know any differently. So, although this routine provides a good idea of what is available, it would be a good idea to provide an option to tell the program that a monochrome display is attached. Microsoft normally uses "/B" for this purpose, so that might be a good standard to stick with. CALL GetDisplay (Adapter%, Mono%) IF Mono% THEN PRINT "Monochrome monitor" ELSE PRINT "Color monitor" END IF SELECT CASE Adapter% CASE 1: PRINT "MDA" CASE 2: PRINT "Hercules" CASE 3: PRINT "CGA" CASE 4: PRINT "EGA" CASE 5: PRINT "MCGA" CASE 6: PRINT "VGA" END SELECT Extended Math page 9 The extended math unit provides an expression evaluator and extensions to BASIC's math. The math extensions include hyperbolic and inverse trig functions, a few handy constants, conversions, and more. You can use the new math routines by including this at the top of your program: $INCLUDE "extmath.inc" $LINK "extmath.pbu" The expression evaluator allows you to find the result of an expression contained in a string. Normal algebraic precedence is used, e.g. 4+3*5 evaluates to 19. The usual numeric operators (*, /, +, -, ^) are supported (multiply, divide, add, subtract, and raise to a power). Use of negative numbers is just fine, of course. Parentheses for overriding the default order of operations are also supported. You may use either a double asterisk ("**") or a caret ("^") symbols to indicate exponentiation. To evaluate an expression, you pass it to the evaluator as a string. You will get back either an error code or a single-precision result. Try this example to see how the expression evaluator works: $STACK 4096 $INCLUDE "extmath.inc" $LINK "extmath.pbu" DO INPUT "Expression? "; Expr$ IF LEN(Expr$) THEN CALL Evaluate (Expr$, Result!, ErrCode%) IF ErrCode% THEN PRINT "Invalid expression. Error = "; ErrCode% ELSE PRINT "Result: "; Result! END IF END IF LOOP WHILE LEN(Expr$) END An expression evaluator adds convenience to any program that needs to accept numbers. Why make someone reach for a calculator when number crunching is what a computer does best? NOTE: The expression evaluator uses recursion and will require more than the default amount of stack space. That's why the $STACK metacommand is used. Extended Math page 10 The new math functions are pretty much self-explanatory, so I'll just list them here. A few general notes are given on the next page. Result% = GCDI%(Nr1%, Nr2%) ' greatest common denominator Result& = GCDL&(Nr1&, Nr2&) ' greatest common denominator Result! = ArcCosHS!(Nr!) ' inverse hyperbolic cosine Result! = ArcSinHS!(Nr!) ' inverse hyperbolic sine Result! = ArcTanHS!(Nr!) ' inverse hyperbolic tangent Result! = ArcCosS!(Nr!) ' arc cosine (1 >= Nr >= -1) Result! = ArcSinS!(Nr!) ' arc sine (1 >= Nr >= -1) Result! = ErfS!(Nr!) ' error function Result! = FactS!(Nr%) ' factorial Result! = CotS!(Nr!) ' cotangent Result! = CscS!(Nr!) ' cosecant Result! = SecS!(Nr!) ' secant Result! = CosHS!(Nr!) ' hyperbolic cosine Result! = SinHS!(Nr!) ' hyperbolic sine Result! = TanHS!(Nr!) ' hyperbolic tangent Result! = Deg2RadS!(Nr!) ' convert degrees to radians Result! = Rad2DegS!(Nr!) ' convert radians to degrees Result! = Cent2Fahr!(Nr!) ' convert centigrade to Fahrenheit Result! = Fahr2Cent!(Nr!) ' convert Fahrenheit to centigrade Result! = Kg2Pound!(Nr!) ' convert kilograms to pounds Result! = Pound2Kg!(Nr!) ' convert pounds to kilograms Pi! = PiS! ' the constant "pi" e! = eS! ' the constant "e" Result# = ArcCosHD#(Nr#) ' inverse hyperbolic cosine Result# = ArcSinHD#(Nr#) ' inverse hyperbolic sine Result# = ArcTanHD#(Nr#) ' inverse hyperbolic tangent Result# = ArcCosD#(Nr#) ' arc cosine (1 >= Nr >= -1) Result# = ArcSinD#(Nr#) ' arc sine (1 >= Nr >= -1) Result# = ErfD#(Nr#) ' error function Result# = FactD#(Nr%) ' factorial Result# = CotD#(Nr#) ' cotangent Result# = CscD#(Nr#) ' cosecant Result# = SecD#(Nr#) ' secant Result# = CosHD#(Nr#) ' hyperbolic cosine Result# = SinHD#(Nr#) ' hyperbolic sine Result# = TanHD#(Nr#) ' hyperbolic tangent Result# = Deg2RadD#(Nr#) ' convert degrees to radians Result# = Rad2DegD#(Nr#) ' convert radians to degrees Pi# = PiD# ' the constant "pi" e# = eD# ' the constant "e" Extended Math page 11 Like BASIC's trig functions, these trig functions expect the angle to be in radians. Conversion functions are provided in case you prefer degrees. Note that there is no ArcTanS! or ArcTanD# function for the simple reason that BASIC supplies an ATN function. Constants are expressed to the maximum precision available. If you are not familiar with variable postfix symbols, here's a summary: Symbol Meaning Range (approximate) ------ -------- ----------------------------------- % integer +- 32767 & long integer +- 2 * 10^9 ! single precision +- 1 * 10^38 (7-digit precision) # double precision +- 1 * 10^308 (15-digit precision) See your BASIC manual or PowerBASIC's online help for further details. Graphics Support page 12 I was rather surprised to find that PowerBASIC lacks support for one of the standard VGA modes-- SCREEN 13, the 320x200 256-color mode. I immediately decided to add support for that mode: dots, lines, boxes, polygons, and (of course) text. While I was at it, I thought I'd add support for a nonstandard VGA mode: 360x480 in 256 colors. This mode will work on almost any plain VGA system, although it might not work on some older not-quite-compatible setups. I'll be adding other modes as I go along, including SuperVGA modes. For now, there are only two modes: 13 320x200, 256 colors, 40x25 text, standard (any VGA) N0 360x480, 256 colors, 45x30 text, nonstandard (almost any VGA) The graphics routines all use the same nomenclature: a G, followed by a mode number, followed by the specific name. This generic naming convention is used so that this chapter can refer to all available modes. For example, if I say "G#Color" and you're using mode 13, you'd actually use "G13Color" in your program. Ok? There are two sets of routines for each mode-- the ones written in ASM and the ones written in BASIC. The file names for these will be suffixed with "A" for ASM and "B" for BASIC. For instance, to use the SCREEN 13 routines, you would add the following at the top of your program: $INCLUDE "g13.inc" $LINK "g13a.obj" $LINK "g13b.pbu" The first thing you will always have to do is to put the screen into the proper mode. This is done with the G#Mode routine: CALL G#Mode (Graphics%) Use 0 to switch to text mode or any other value to switch to graphics mode. One difference between BASIC and BasWiz is that, instead of each "draw" command requiring a color parameter as in BASIC, the PBWiz library provides a separate color command: CALL G#Color (Foreground%, Background%) The "foreground" color is used by all graphics routines. The background color is used by the G#Cls routine. Both foreground and background colors are used in the G#Write and G#WriteLn routines. Graphics Support page 13 Here is a list of the corresponding routines, first BASIC, then PBWiz (replace the "#" with the appropriate mode number): ' get the color of a specified point colour% = POINT(x%, y%) colour% = G#GetPel%(x%, y%) ' set the color of a specified point PSET (x%, y%), colour% CALL G#Color (colour%, backgnd%): CALL G#Plot (x%, y%) ' draw a line of a specified color LINE (x1%, y1%) - (x2%, y2%), colour% CALL G#Color (colour%, backgnd%): CALL G#Line (x1%, y1%, x2%, y2%) ' draw a box frame of a specified color LINE (x1%, y1%) - (x2%, y2%), colour%, B CALL G#Color (colour%, backgnd%): CALL G#Box (x1%, y1%, x2%, y2%, 0) ' draw a box of a specified color and fill it in LINE (x1%, y1%) - (x2%, y2%), colour%, BF CALL G#Color (colour%, backgnd%): CALL G#Box (x1%, y1%, x2%, y2%, 1) ' clear the screen and home the cursor CLS CALL G#Cls ' get the current cursor position Row% = CSRLIN: Column% = POS(0) CALL G#GetLocate (Row%, Column%) ' set the current cursor position LOCATE Row%, Column% CALL G#Locate (Row%, Column%) ' display a string without a carriage return and linefeed PRINT St$; CALL G#Write (St$) ' display a string with a carriage return and linefeed PRINT St$ CALL G#WriteLn (St$) Note that PBWiz, unlike BASIC, allows both foreground and background colors for text in graphics mode. Graphics Support page 14 If you need to print a number rather than a string, just use the BASIC function STR$ to convert it. If you don't want a leading space, use this approach: St$ = LTRIM$(STR$(Number)) The PBWiz library has other routines which have no BASIC equivalent. One allows you to get the current colors: CALL G#GetColor (Foreground%, Background%) Circles and ellipses can be drawn with the Ellipse routine. This is similar to the BASIC CIRCLE statement. You specify the center of the ellipse (X,Y), plus the X and Y radius values: CALL G#Ellipse (CenterX%, CenterY%, XRadius%, YRadius%) A circle is an ellipse with a constant radius. So, to draw a circle, just set both radius values to the same value. As well as the usual points, lines, and ellipses, PBWiz also allows you to draw regular polygons: triangles, squares, pentagons, hexagons, and so on. CALL G#Polygon (X%, Y%, Radius%, Vertices%, Angle!) The X% and Y% values represent the coordinates of the center of the polygon. The Radius% is the radius of the polygon (as if you were fitting it into a circle). Vertices% is the number of angles (also the number of sides) for the polygon to have. Angle! specifies the rotation of the polygon, and is specified in radians. Mouse Support page 15 The mouse unit provides full-featured mouse support. You can see if a mouse is available and how many buttons it has, get the cursor position (either the current position or the position at the last press or release of a specified button), set the cursor position, change the cursor, set the mouse range, get hardware information about the mouse, and so on. This unit is called MOUSE, so you access it by including the following lines at the top of your program: $INCLUDE "mouse.inc" $LINK "mouse.obj" There are two unusual mouse modes to be aware of. One is text mode, which is mapped to a 640x200 virtual display. So, to convert the results to text format, you need to divide the cursor position by eight and add one. To convert from text format, subtract one and multiply by eight. The second unusual mode is 320x200 CGA mode, which is also mapped to 640x200. To convert the coordinates to this mode, divide X by two. To convert from this mode, multiply the X coordinate by two. All other modes use the actual display coordinates instead of a bizarro virtual screen. Why the peculiar CGA and text modes? Well, evidently Microsoft never thought there'd be any video adapters besides MDA and CGA, and decided to create a single virtual screen size that worked for all modes. Not a bad idea, I guess, but rather shortsighted. Oh well. One other nuisance that you may run into is that the mouse cursor can't be directly turned on or off. A "cursor visibility" count is maintained-- if the mouse cursor was turned on twice, you'll need to turn it off twice before it will actually disappear. Before using the mouse, you must initialize it. The initialization routine also checks to make sure that a mouse is installed and tells you how many buttons it has. It's best to initialize the mouse after setting the screen mode, so the mouse driver understands what mode you're using. Not all mouse drivers support all screen modes, but you can reasonably expect any current mouse driver to support MDA, CGA, EGA, and VGA. Hercules graphics mode is rarely supported, as it must be set through direct hardware access rather than the standard techniques, so the mouse driver has little way of knowing that you've changed the mode. The mouse routines will work equally well with two-button or three-button rodents. The middle button functions will return 0 with two-button mice. I won't go into great detail on these routines, because they're pretty much self-explanatory. The mouse is a fairly easy device to deal with. Mouse Support page 16 You can initialize the mouse driver like so: Buttons% = MouseInit% This returns the number of mouse buttons available. If there is no mouse, zero will be returned. Initialize the mouse after setting the screen mode. You can make the mouse cursor visible or invisible. It will function just as well in either state. See the previous page for some quirks. CALL MouseShow ' show the cursor CALL MouseHide ' hide the cursor There are many ways to get the mouse cursor position. You can get the current position, the position at which the mouse was located when a particular button was pressed, or the position when a button was released. If you choose a past position, you can also find out how many presses or releases of the button have taken place since you last checked. X% = MouseWhereX% ' return current X coordinate Y% = MouseWhereY% ' return current Y coordinate CALL MouseLClick (Count%, X%, Y%) ' left presses and posn at last press CALL MouseMClick (Count%, X%, Y%) ' middle presses & posn at last press CALL MouseRClick (Count%, X%, Y%) ' right presses & posn at last press CALL MouseLRelease (Count%, X%, Y%) ' left releases and posn at last rel. CALL MouseMRelease (Count%, X%, Y%) ' middle releases & posn at last rel. CALL MouseRRelease (Count%, X%, Y%) ' right releases & posn at last rel. If you'd prefer to find out which buttons are currently pressed, no problem: Pressed% = MouseLButton% ' whether the left button is pressed Pressed% = MouseMButton% ' whether the middle button is pressed Pressed% = MouseRButton% ' whether the right button is pressed Of course, if you can get the cursor position, you must be able to set it: CALL MouseLocate (X%, Y%) ' set the mouse cursor position The mouse cursor range can be restricted to a given area of the screen. This area is expressed by giving the upper left corner and lower right corner of the rectangular area to which to restrict the cursor. CALL MouseWindow (X1%, Y1%, X2%, Y2%) Mouse Support page 17 There are a variety of cursor shapes available for graphics mode: 0 hourglass (standard "please wait, I'm working" symbol) 1 pointing arrow (default) 2 pointing hand 3 crosshair 4 target (box in a box) 5 grabbing hand If you have ideas for more, let me know and I'll see what I can do. The cursor image is set like so: CALL MouseCursorG (CursorNr%) Strings page 18 One of the true strengths of BASIC lies in its powerful string handling capability. I'd be remiss if I didn't provide extensions which improve it even further. This unit can be accessed by including these lines at the top of your program: $INCLUDE "string.inc" $LINK "stringa.obj" $LINK "stringb.pbu" The simplest of the PBWiz string routines may seem somewhat whimsical, but it has proven useful to me on several occasions in the past. It reverses the order of characters in a string. CALL Reverse (St$) One of the places this has come in useful is in searching a string from the end-- a reverse INSTR routine: CALL RInstr (MainSt$, SubSt$, Posn%) Rather than returning the first occurrence of a substring within a main string, it returns the last occurrence. Another handy string search allows you to search for various types of characters, rather than a specific substring: CALL TInstr (MainSt$, Types%, Posn%) The type(s) may be specified using any combination of the following. Just add them together. 1 alphabetic 2 numeric 4 symbolic 8 control 16 graphics 32 space Since you can search for any specific types, you can also readily invert the search to look for any characters that are NOT of a given type or types: Types% = NOT Types% This gives you complete control. A typical use for TInstr might be to clean up user input and make sure that it's valid. It's also good for parsing. Strings page 19 Another routine that is useful for cleaning up and parsing user input is called Crunch. It allows you to eliminate adjacent duplicates of a character or list of characters. One use for this, for instance, would be to eliminate repeated spaces, converting an input string from "*.* *.BAK /B" to a more manageable "*.* *.BAK /B". Result$ = Crunch$(St$, CharList$) There are a pair of routines that you'll find valuable if you need to check the validity of a string. These are designed to be compatible with the Xmodem and Ymodem file transfer protocols, so you can use them for error checking in telecommunications as well. Chk% = CheckSum% (St$) CALL CRC16 (St$, HiCRC%, LoCRC%) Another pair of string routines provide a simple encryption/decryption system for text. The method used is not particularly secure but are very fast and will be adequate for many purposes. As always, it helps to use a long and/or complex password. CALL Cipher (St$, Password$) CALL CipherP (St$, Password$) Both of these routines will encipher text on the first run-through and decipher on the second, so you can use the same routine either to encrypt or decrypt a message. They are different in one respect: the encrypted result of Cipher may contain control characters, so it can't be used in a plain sequential-access file. The CipherP routine does not allow use of extended ASCII characters (CHR$(128) - CHR$(255)), as it sets the high bit on each character after encrypting it. This causes the results of CipherP to be printable (and useful in sequential-access files), although they will look very strange. The strings are encrypted (or decrypted) in place. This provides a certain extra measure of security for encryption-- the original plaintext strings are not left floating around in memory where someone might see them. One function is as much a file manipulation routine as it is a string function. It allows you to compare a file name to a file pattern (which may contain wildcards) to see if they match. Only bare filespecs are supported-- you may not use drive or path specifications in the names. IF MatchFile%(Pattern$, Filename$) THEN PRINT Filename$ This can be used in creating your own DOS-style utilities: DIR, COPY, and so forth. Besides the usual "accept file if it matches" approach, it can also be used to implement the opposite: "exclude file if it matches." This gives you more flexibility than DOS itself supplies. Strings page 20 The PowerBASIC compiler provides a very nice function called Extract$. This allows you to retrieve a substring running from the left side of a main string to a specified character delimiter. Not bad, but it might be handy to be able to grab a numbered substring from any part of a main string, and to be able to use a substring delimiter. For instance, you might load a record from a database which contains an address, where each line is delimited by a carriage return and linefeed. Rather than mucking around with Extract$, which really wasn't designed with that sort of thing in mind, you'd do better to use the PBWiz function called DelimExtract$: SubSt$ = DelimExtract$(St$, Delimiter$, Index%) The index starts at 1 with the first substring. If you choose the index of a substring which doesn't actually exist, a null string will be returned. Credits page 21 I'd like to thank Dave Navarro for letting me in on the world of PowerBASIC. His assistance has been most valuable to me in many respects. Without him, this library would have taken much longer to get off the ground or would perhaps not even exist. Dave runs the excellent Bard's Lair BBS-- see my WHERE.BBS file for more details. I would also like to thank Spectra, publishers of PowerBASIC, for sending me the evaluation copy which led to my decision to write this library.