ProfitPress Mega CDROM2 Shareware Freeware (MSDOS)(1992)(Eng)

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

/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / PROG / BASIC / PBCLON17.ZIP / PBCLONE1.MAN < prev next >

Wrap

Text File | 1991-12-10 | 133.2 KB | 3,659 lines

Name : AddMatI (Add Matrix Integer) Class : Array management Level : Any This routine adds an integer to as many elements of an integer array as you like, starting at a specified place in the array. It can also be used to subtract (just specify a negative value). If there was a numeric overflow at any point in the operation, an error code will be returned. AddMatI DSeg%, DOfs%, Elements%, Value%, ErrCode% DSeg% segment of the first array element to add, obtained by VARSEG DOfs% offset of the first array element to add, obtained by VARPTR Elements% number of array elements to which to add Value% value to add to each array element ------- ErrCode% error code: 0 if no error, else there was an overflow Name : AddMatL (Add Matrix Long integer) Class : Array management Level : Any This routine adds a long integer to as many elements of an long integer array as you like, starting at a specified place in the array. It can also be used to subtract (just specify a negative value). If there was a numeric overflow at any point in the operation, an error code will be returned. AddMatL DSeg%, DOfs%, Elements%, Value&, ErrCode% DSeg% segment of the first array element to add, obtained by VARSEG DOfs% offset of the first array element to add, obtained by VARPTR Elements% number of array elements to which to add Value& value to add to each array element ------- ErrCode% error code: 0 if no error, else there was an overflow Name : AllExtMem& (All Extended Memory) Class : Equipment Level : Clone (AT) This routine returns the amount of extended memory installed in the system, as reported by the power-on self-test (POST) routine at boot time. This does not tell you how much extended memory is actually available, since extended memory may be carved up by users of BIOS-level extended memory or XMS memory, converted to expanded memory, etc. It only tells you the amount of physical extended memory that is installed. Do not use this routine on PC/XT machines. It is only for AT-class computers. ExtMemKb& = AllExtMem& ------- ExtMemKb& kilobytes of extended memory installed Name : AltKey (Alt Key) Class : Input Level : Any This routine works in conjunction with a key input routine, such as INKEY$ or the CheckKey and GetKey routines. Given the ASCII code and scan code of a key, AltKey returns the associated key letter, if any. For instance, it returns "A" if you pass it ASCII code 0 and scan code 30, because those codes represent Alt-A. AltKey ASCIICode%, ScanCode%, Ky$ ASCIICode% ASCII code of the key ScanCode% scan code of the key ------- Ky$ associated key letter ("" if none) Name : AndSt (AND String) Class : String Level : Any This routine ANDs each byte in one string with the corresponding byte in a second string. The strings must be the same length. AndSt St1$, St2$ St1$ string to AND St2$ string to AND with ------- St1$ result Name : Any2Dec (Any to Decimal) Class : Numeric Level : Any This routine converts a number in any base to a normal (base 10) integer. It works like the &H and &O prefixes in BASIC, but rather than working only in hexadecimal (base 16) and octal (base 8), it can be used for binary, octal, or almost anything else. If you specify base 10, you can use this routine to convert a signed integer (0-65,535) to a normal integer. Any2Dec Number$, NrBase%, DecNr%, ErrCode% Number$ any-base number to convert to an integer NrBase% number base to convert from ------- DecNr% resulting integer ErrCode% error code: 0 if no error, else overflow, bad base, or invalid nr Name : AscI% (ASC Integer) Class : String Level : Any This is a replacement for the ASC function provided by BASIC. It is smaller than ASC, however, and also somewhat faster. Unlike BASIC or ProBas, the PBClone AscI function returns -1 as an error condition if you try to use it on a null string. This convention owes its origin to the similar routine in Crescent's libraries. Value% = AscI%(St$) St$ string for which to return ASCII code ------- Value% code of the first string character or -1 if null string Name : BarMenu (Bar Menu) Class : Input Level : Clone This is a bar menu routine. It allows the user to select one of a list of items given on a single menu row or "bar". The current item is highlighted in your choice of colors; user selection can be done either by moving this highlight and pressing return or by entering the letter associated with the desired item. Only text mode is supported. The highlight may be moved with the left and right arrow keys, tab and backtab, or space and backspace. Selection is done with <CR>, the enter key. The letter used to select an item is the first character of the item that is not lowercase or a space. If the item is all lowercase, the first character of the item will be used. For example, suppose you want the user to select one of "list" or "log". By passing the options to BarMenu as "List" and "lOg", you allow the user to press "L" for "List" and "O" for "lOg". The user's choice will be returned to you as a number, with the first choice being numbered 1. If <ESC> was pressed, 0 will be returned. BarMenu PickList$(), Row%, LeftCol%, RightCol%, Attr%, HiAttr%, Prompt$ PickList$() list of items to choose from Row% row on which to display the bar LeftCol% leftmost column of the bar RightCol% rightmost column of the bar (use -1 for auto-sizing) Attr% bar color/attribute (see CalcAttr) HiAttr% bar highlight color/attribute (see CalcAttr) Prompt$ prompt text (displayed at the left side of the bar) ------- Row% number of the chosen item (1-items, or 0 if <ESC>) Name : BarMenuM (Bar Menu with Mouse) Class : Input, Mouse Level : Clone This is a bar menu routine. It functions just like BarMenu, but supports the use of a mouse as well as the keyboard. BarMenuM PickList$(), Row%, LeftCol%, RightCol%, Attr%, HiAttr%, Prompt$, Mouse%, ShowCursor% PickList$() list of items to choose from Row% row on which to display the bar LeftCol% leftmost column of the bar RightCol% rightmost column of the bar (use -1 for auto-sizing) Attr% bar color/attribute (see CalcAttr) HiAttr% bar highlight color/attribute (see CalcAttr) Prompt$ prompt text (displayed at the left side of the bar) Mouse% whether a mouse is available (0 no) ShowCursor% not used ------- Row% number of the chosen item (1-items, or 0 if <ESC>) Name : Bickel (Bickel comparison) Class : String Level : Any A string comparison routine, Bickel allows you to see how closely two strings match. The better the match, the larger the returned value will be. Since there is no constant minimum or maximum value, this routine is best used for applications involving dictionary searches. You would scan the dictionary and make a list of the best matches. This is appropriate for a spelling checker, for instance. Bickel St1$, St2$, Result% St1$ first string to compare St2$ second string to compare ------- Result% resulting "match magnitude" value Name : BigPrint (Big Print) Class : Display Level : BIOS As the name suggests, this routine displays text in large characters. How large? Eight times as high and as wide as normal! Each "big character" will be composed of many normal-sized characters. You may choose the normal character used to create the big characters (the default is a CHR$(219) solid block character, if you pass a null string here). You should avoid using CHR$(128) to CHR$(255) when in either of the CGA graphics modes, as many CGAs are unable to display these characters when in graphics mode. BigPrint St$, FormCh$, Row%, Column%, Attr% St$ string to display in big characters FormCh$ character used to compose the big characters Row% starting row Column% starting column Attr% color/attribute of big characters (see CalcAttr) Name : BinSeekD (Binary Seek Double precision) Class : Array management Level : Any This routine uses binary search techniques to locate a specific number in a sorted double-precision array. Each number in the array must be unique (no duplicates) for this to work. This is a very, very fast routine and is especially handy for look-up tables. The array is expected to begin at element 1. You may specify the maximum element to search, allowing use of only part of an array. A single number is returned in Posn%. If Posn% is greater than zero, the target number was found and Posn% is the position in the array where it was found. If Posn% is negative, the target number was not found, but it could be inserted into the array at the -Posn% element. If the number is zero, the target number was not found and there is no room in the array to add any more values. BinSeekD Array#(), Elements%, Target#, Posn% Array#() array of sorted, unique values to search Elements% maximum array element to search Target# value to look for ------- Posn% whether and where the target was found (see above for details) Name : BinSeekI (Binary Seek Integer) Class : Array management Level : Any This routine uses binary search techniques to locate a specific number in a sorted integer array. Each number in the array must be unique (no duplicates) for this to work. This is a very, very fast routine and is especially handy for look-up tables. The array is expected to begin at element 1. You may specify the maximum element to search, allowing use of only part of an array. A single number is returned in Posn%. If Posn% is greater than zero, the target number was found and Posn% is the position in the array where it was found. If Posn% is negative, the target number was not found, but it could be inserted into the array at the -Posn% element. If the number is zero, the target number was not found and there is no room in the array to add any more values. BinSeekI Array%(), Elements%, Target%, Posn% Array%() array of sorted, unique values to search Elements% maximum array element to search Target% value to look for ------- Posn% whether and where the target was found (see above for details) Name : BinSeekL (Binary Seek Long integer) Class : Array management Level : Any This routine uses binary search techniques to locate a specific number in a sorted long integer array. Each number in the array must be unique (no duplicates) for this to work. This is a very, very fast routine and is especially handy for look-up tables. The array is expected to begin at element 1. You may specify the maximum element to search, allowing use of only part of an array. A single number is returned in Posn%. If Posn% is greater than zero, the target number was found and Posn% is the position in the array where it was found. If Posn% is negative, the target number was not found, but it could be inserted into the array at the -Posn% element. If the number is zero, the target number was not found and there is no room in the array to add any more values. BinSeekL Array&(), Elements%, Target&, Posn% Array&() array of sorted, unique values to search Elements% maximum array element to search Target& value to look for ------- Posn% whether and where the target was found (see above for details) Name : BinSeekS (Binary Seek Single precision) Class : Array management Level : Any This routine uses binary search techniques to locate a specific number in a sorted single-precision array. Each number in the array must be unique (no duplicates) for this to work. This is a very, very fast routine and is especially handy for look-up tables. The array is expected to begin at element 1. You may specify the maximum element to search, allowing use of only part of an array. A single number is returned in Posn%. If Posn% is greater than zero, the target number was found and Posn% is the position in the array where it was found. If Posn% is negative, the target number was not found, but it could be inserted into the array at the -Posn% element. If the number is zero, the target number was not found and there is no room in the array to add any more values. BinSeekS Array!(), Elements%, Target!, Posn% Array!() array of sorted, unique values to search Elements% maximum array element to search Target! value to look for ------- Posn% whether and where the target was found (see above for details) Name : BinSeekSt (Binary Seek String) Class : Array management Level : Any This routine uses binary search techniques to locate a specific string in a sorted string array. Each string in the array must be unique (no duplicates) for this to work. This is a very, very fast routine and is especially handy for look-up tables. The string array is expected to begin at element 1. You may specify the maximum element to search, allowing use of only part of an array. You must specify whether capitalization matters-- set CapsCount% to 0 if it doesn't. A single number is returned in Posn%. If the number is greater than zero, the target string was found, and the number is the position in the array where it was found. If the number is negative, the target string was not found, but it could be inserted into the array at the -Posn% element. If the number is zero, the target string was not found and there is no room in the array to add any more values. BinSeekSt Array$(), Elements%, Target$, CapsCount%, Posn% Array$() array of sorted, unique values to search Elements% maximum array element to search Target$ string to look for CapsCount% 0 if capitalization doesn't matter ------- Posn% whether and where the target was found (see above for details) Name : BIOSInkey (BIOS INKEY$) Class : Input Level : BIOS BIOSInkey works like INKEY$, but it gets its key directly by asking the BIOS. The primary advantage of this is that you get the "scan" code as well as the ASCII code of the key. The scan code is independent of the shift status-- for instance, the scan code for "A" is the same as the scan code for "a" or Control-A or Alt-A. This can be very handy. If there is no key available, both the scan code and ASCII code will be zero. BIOSInkey AscCode%, ScanCode% ------- AscCode% ASCII code of the key, if any ScanCode% scan code of the key, if any Name : BkScroll (Backward Scroll) Class : Display Level : BIOS This routine scrolls any selected part of the display down-- it does a backwards scroll. You may scroll as many times as you like, or scroll "zero" times to totally clear the selected part of the display. Note that BIOS-level scrolling can cause the screen to flicker on some CGAs due to a combination of unfortunate design factors. BkScroll TopRow%, LeftCol%, BottomRow%, RightCol%, Times% TopRow% top row of the area to scroll LeftCol% left column of the area to scroll BottomRow% top row of the area to scroll RightCol% left column of the area to scroll Times% number of times (or rows) to scroll Name : BkSpace (Backspace) Class : Display Level : BIOS Although CHR$(8) is supposed to mean "backspace", it shows up as a graphics character when BASIC prints it. This routine does an actual backspace with full wrap-- if it's at the beginning of the line, it will move back to the previous line (if there is one). It backspaces destructively (erasing the previous character) from the current cursor position. The new cursor is returned to you, since QuickBASIC may ignore the new status. BkSpace Row%, Column% ' do the backspace LOCATE Row%, Column% ' inform QuickBASIC ------- Row% new row Column% new column Name : Blink (Blink toggle) Class : Display Level : BIOS / Clone (see text) It is possible to make characters in text mode blink by giving them an appropriate "color". I wouldn't mention something so obvious but for another possibility which is less widely known: blinking can be turned off, in which case the characters that would have otherwise blinked will instead have a bright background. In other words, turn off blinking, and you double the possible number of background colors. This technique will always work with EGA and VGA displays. It can also be used with MDA/Hercules and CGA displays, on which it will almost always work... unfortunately, on some less-than-perfect PC clones, it will cause the computer to lock up instead. So, be careful with this one! Blink SetBlink% SetBlink% whether to blink (-1) or use intense backgrounds (0) Name : BlockMove (Block memory Move) Class : Memory Level : Clone This routine allows you to copy or "move" a block of data from one memory location to another. It isn't very bright, so if the memory areas overlap, you will have to tell the routine to "move backwards" instead of forwards. In that case, you will also have to change the offsets to point to the ends of the memory areas instead of the beginnings. Normally, you can use forward moves. In that case, the offsets you specify are those of the beginning of the memory areas. If backward moves are required, the offsets specified are those of the end of the memory areas. If you are familiar with assembly language, you may recognize this as a straightforward implementation of the "REP MOVSB" instruction. You may move up to 65,520 bytes at a time, provided that the addresses are in normalized form (if you don't know what this means, you probably don't need to worry about it). This routine can be used to copy information to an array from any area of memory (the BIOS data area, the screen, another array, etc), or vice versa. It can also be used to do things like insert/delete elements from an array, scroll the screen, fill the screen with a specified character, and so on. BlockMove FromSeg%, FromOfs%, ToSeg%, ToOfs%, Bytes&, Direction% FromSeg% segment of the area from which to copy FromOfs% offset of the area from which to copy ToSeg% segment of the area to which to copy ToOfs% offset of the area to which to copy Bytes& number of bytes to copy (0-65,520) Direction% direction to copy (0 if forward, else backward) Name : BootDrive (get Boot Drive) Class : Disk Level : DOS 4.0+ This routine tells you which drive was used to boot the system. See also BootDrive2, a function version of this routine. One use for BootDrive would be in installation programs, to determine the most likely destination drive for your software. Drive$ = "x" BootDrive Drive$ ------- Drive$ boot drive-- set it to at least one char beforehand! Name : BootDrive2$ (get Boot Drive) Class : Disk Level : DOS 4.0+ This routine tells you which drive was used to boot the system. One use for BootDrive2 would be in installation programs, to determine the most likely destination drive for your software. Drive$ = BootDrive2$ ------- Drive$ boot drive (null if wrong DOS version) Name : BreakCheck% (Break key Check) Class : Input Level : BIOS This routine is for use after BreakOff. It allows you to see whether the Break key has been pressed since you last checked. The Break status is cleared after the value is returned. Brk% = BreakCheck% IF Brk% THEN PRINT "** Break key pressed **" GOTO EndProgram END IF ------- Brk% whether Break was pressed (0 no, -1 yes) Name : BreakOff (Break key Off) Class : Input Level : BIOS This routine disables the Break key. It is not effective in the QB or QBX environments, as these use their own keyboard handler. It is also not effective if your program was compiled with Debugging on (/D switch). Note that BreakOff installs a routine to intercept some interrupt vectors. You MUST use the BreakOffDone routine to reverse this process before your program ends, or the computer will be left in an indeterminate state and will probably crash the next time Break is pressed! BreakOff Name : BreakOffDone (Break key Off routine Done) Class : Input Level : BIOS This routine is used after BreakOff to restore the original interrupt vectors. If you use BreakOff, you MUST call BreakOffDone before your program ends! Otherwise, the computer will probably crash the next time someone presses Break. BreakOffDone Name : BSq (Blank Squeeze) Class : String Level : Any A simple compression routine, BSq "squeezes" the blank spaces in a string. It is designed expressly for use with text data. The text may not contain more than 131 spaces in a row, or CHR$(128) through CHR$(255), which are used in the compression. Average text files are liable to be compressed by around 16%. Files that contain more spaces, such as structured programs, will benefit more. The compression algorithm is simple but extremely fast, adding no noticeable overhead to string processing. See also BUsq, BUsqLen. BSq St$, StLen% St$ = LEFT$(St$, StLen%) St$ string to compress ------- St$ compressed string StLen% length of the compressed string Name : BUsq (Blank Unsqueeze) Class : String Level : Any This routine is used to uncompress strings that were processed by BSq. Before uncompression, the BUsqLen routine must be used to find out how long the resulting string will be. See also BSq, BUsqLen. BUsqLen St$, StLen% IF StLen% < 0 THEN PRINT "Error in compressed string" ELSE Result$ = SPACE$(StLen%) BUsq St$, Result$ END IF St$ string to uncompress ------- Result$ uncompressed string Name : BUsqLen (Blank Unsqueeze Length) Class : String Level : Any This routine is used in coordination with BUsq to uncompress strings that were processed by BSq. It determines what the length of the uncompressed string will be, which is necessary to initialize the string for BUsq. See also BSq, BUsq. BUsqLen St$, StLen% IF StLen% < 0 THEN PRINT "Error in compressed string" ELSE Result$ = SPACE$(StLen%) BUsq St$, Result$ END IF St$ string to uncompress ------- StLen% length of the uncompressed string Name : CalcAttr (Calculate Attribute) Class : Display Level : Any Many of the display routines in this library require an "attribute" rather than foreground and background colors. An attribute is a combination of the foreground and background colors in a format which is used by all types of displays when in text mode. Foreground colors are usually specified as 0-31, with backgrounds as 0-7. If you turn blinking off (see Blink), it may be more convenient to express the same thing as foreground 0-15, background 0-15. The CalcAttr routine will accept either way of expressing it. Note, however, that UnCalcAttr will always return the former pair of results, since it has no way of knowing whether Blink has been used (foreground 0-31, background 0-15). See UnCalcAttr for more details and a solution. See also CalcAttr2, the FUNCTION version of this routine. CalcAttr Foreground%, Background%, Attr% Foreground% foreground color Background% background color ------- Attr% color "attribute" Name : CalcAttr2% (Calculate Attribute) Class : Display Level : Any Many of the display routines in this library require an "attribute" rather than foreground and background colors. An attribute is a combination of the foreground and background colors in a format which is used by all types of displays when in text mode. Foreground colors are usually specified as 0-31, with backgrounds as 0-7. If you turn blinking off (see Blink), it may be more convenient to express the same thing as foreground 0-15, background 0-15. The CalcAttr2 routine will accept either way of expressing it. Note, however, that UnCalcAttr will always return the former pair of results, since it has no way of knowing whether Blink has been used (foreground 0-31, background 0-15). See UnCalcAttr for more details and a solution. See also CalcAttr, the SUB version of this routine. Attr% = CalcAttr2%(Foreground%, Background%) Foreground% foreground color Background% background color ------- Attr% color "attribute" Name : CalcDate (Calculate Date) Class : Time Level : Any This routine calculates what the date will be a given number of days from now, either in the past or the future. Actually, you may use any starting date, not just the current date. An error code is returned if the starting date or resulting date are not valid. Dates may not preceed January 1, 1900. CalcDate accepts the date in any standard form ("01/30/91" or "01-30-1991", for example) and returns its results in the same format. CalcDate StartDate$, Days&, Direction%, NewDate$, ErrCode% StartDate$ starting date Days& number of days from the current date (0 or more) Direction% whether to return result in the future (0) or past (nonzero) ------- NewDate$ resulting date ErrCode% whether the dates are valid (0 yes) Name : CalcSize (Calculate array Size) Class : Display Level : Any This routine calculates the necessary DIM size for an integer array, assuming that you intend to store display data in the array. This is most useful in conjunction with DGetScreen and GetScreen. CalcSize TopRow%, LeftCol%, BottomRow%, RightCol%, Elements% DIM Array%(1 TO Elements%) TopRow% top row of the display area LeftCol% left column of the display area BottomRow% top row of the display area RightCol% left column of the display area ------- Elements% required size of the integer array Name : CalcVGAColor (Calculate VGA palette Color) Class : Display Level : Any The QuickBASIC manual gives a cumbersome formula for calculating VGA palette colors. This routine does it faster and with less fuss. All you need to do is pass it the appropriate intensity values (0-63) and you get back a long integer, just the way BASIC wants it. CalcVGAColor Red%, Green%, Blue%, Colour& Red% red intensity Green% green intensity Blue% blue intensity ------- Colour& color value for use in the PALETTE statement Name : Carrier (detect Carrier) Class : Serial Level : Clone If you write communications programs, particularly things like doors and BBSes, you probably want to keep an eye on the carrier. BASIC won't do it, but we will! Carrier CommPort%, CarrierHigh% CommPort% serial port number (1-4, although BASIC only handles 1-2) ------- CarrierHigh% zero if no carrier Name : CatchError (Catch Error from SHELL) Class : Miscellaneous Level : Clone The CatchError routine is used in conjunction with GetError. It lets you get the exit code (error level) returned by a program to which you have SHELLed. Since CatchError hooks an interrupt to do its work, you must always make sure to use GetError afterwards to "clean up". See also GetError. Note that differences in DOS mean that this routine will not always work. In some versions of DOS, you can only get the error level if a batch file was executed; in others, you can't get the error level from a batch file at all. Sorry about that. I don't know of any way to work around it. CatchError SHELL ProgramName$ GetError ExitCode% Name : CDROM (check for CD-ROM) Class : Disk / Equipment Level : DOS This routine tells you whether the Microsoft CD-ROM Extensions are installed. If so, it tells you what the letter of the first CD-ROM logical drive is and how many logical drives exist. Note: 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. This may cause unexpected results. I'm not yet sure whether DOS 5.0 is similarly afflicted. FirstDrive$ = "x" CDROM FirstDrive$, Drives% ------- FirstDrive$ letter of the first logical drive (init to at least one space!) Drives% number of logical drives available (0 if no CD-ROM is there) Name : CDROM2% (check for CD-ROM) Class : Disk / Equipment Level : DOS This routine tells you whether the Microsoft CD-ROM Extensions are installed. If so, it tells you how many logical drives exist. Note: 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. This may cause unexpected results. I'm not yet sure whether DOS 5.0 is similarly afflicted. Drives% = CDROM2% ------- Drives% number of logical drives available (0 if no CD-ROM is there) Name : CheckDate (Check Date validity) Class : Time Level : Any This routine checks a date to see if it is valid. CheckDate MonthNr%, DayNr%, YearNr%, ErrCode% MonthNr% month number (1-12) DayNr% day number (1-31) YearNr% year number (1900 on; years <100 will be assumed 20th century) ------- ErrCode% whether the date is valid (0 yes) Name : CheckDisk (Check Disk readiness) Class : Disk Level : DOS The CheckDisk routine determines whether a disk is ready. About the only thing it won't tell you is if a disk is write-protected or out of space. Since the PBClone disk routines all contain critical error handling, which reports back an appropriate error code for all such problems, this routine isn't really needed any more. It's included for compatibility with older ProBas programs. Note that DOS versions before 3.0 do not return as useful error codes as later versions. Under such circumstances, both "unformatted disk" and "open drive door" will be returned as "open drive door". CheckDisk Drive$, ErrCode% Drive$ letter of the drive to check ------- ErrCode% 0: no error; 1: unformatted disk; 2: open drive door; 3: bad drive Name : CheckDsk% (Check Disk readiness) Class : Disk Level : DOS The CheckDsk% function determines whether a disk is ready. About the only thing it won't tell you is if a disk is write-protected or out of space. Since the PBClone disk routines all contain critical error handling, which reports back an appropriate error code for all such problems, this routine isn't really needed any more. It's included for compatibility with older ProBas programs. Note that DOS versions before 3.0 do not return as useful error codes as later versions. Under such circumstances, both "unformatted disk" and "open drive door" will be returned as "open drive door". ErrCode% = CheckDsk%(Drive$) Drive$ letter of the drive to check Name : CheckKey (Check for Key or mouse) Class : Input, Mouse Level : BIOS This routine is kind of an extended version of INKEY$. It checks the keyboard to see if any key is available and gets the key if it is. At your option, it can also check the mouse to see if a button has been pressed. CheckKey Mouse%, ASCIIcode%, ScanCode%, LeftButton%, RightButton% Mouse% whether to check the mouse (0: no) ------- ASCIIcode% ASCII code of the key pressed ScanCode% scan code of the key pressed (0 if none) LeftButton% whether the left mouse button was pressed RightButton% whether the right mouse button was pressed Name : CheckKey3 (Check for Key or 3-button mouse) Class : Input, Mouse Level : BIOS This routine is kind of an extended version of INKEY$. It checks the keyboard to see if any key is available and gets the key if it is. At your option, it can also check the mouse to see if a button has been pressed. CheckKey3 Mouse%, ASCIIcode%, ScanCode%, LeftButton%, MidBttn%, RightButton% Mouse% whether to check the mouse (0: no) ------- ASCIIcode% ASCII code of the key pressed ScanCode% scan code of the key pressed (0 if none) LeftButton% whether the left mouse button was pressed MidBttn% whether the middle mouse button was pressed RightButton% whether the right mouse button was pressed Name : CheckShare (Check for SHARE) Class : Disk Level : DOS The CheckShare routine determines whether SHARE.EXE is active. This is particularly helpful before using the BASIC OPEN statement, which will fail if you request file sharing when it's not available. The PBClone file routines handle such situations automatically, so CheckShare is not needed for them. CheckShare ShareActive% ------- ShareActive% whether SHARE is active (0 if no) Name : CheckShare2% (Check for SHARE) Class : Disk Level : DOS The CheckShare2% function determines whether SHARE.EXE is active. This is particularly helpful before using the BASIC OPEN statement, which will fail if you request file sharing when it's not available. The PBClone file routines handle such situations automatically, so CheckShare2% is not needed for them. ShareActive% = CheckShare2% ------- ShareActive% whether SHARE is active (0 if no) Name : Checksum (calculate Checksum) Class : String / Serial Level : Any The Checksum routine calculates a checksum on a string. The resulting number is compatible with Xmodem and Ymodem checksum routines and will vary from 0-255. This checksum provides a minimal, but fast, check of what characters are contained in the string. See also CRC1. Checksum St$, ChkSum% St$ string to process ------- ChkSum% checksum of the characters in the string Name : Cipher (Cipher) Class : String Level : Any This is a very simple text encryption routine. It isn't particularly hard to crack, but will provide a basic level of security for undemanding applications. The same routine can be used either to encrypt or decrypt text. The original text may contain any character; likewise, the resulting text. This is not well suited for use with sequential files-- if such is required, see CipherP. I'd suggest using a long password composed of an unlikely string of characters, e.g. "#*@@!A^%x{.'". Cipher St$, Password$ St$ string to encrypt or decrypt Password$ password ------- St$ encrypted or decrypted string Name : CipherP (Cipher Printable) Class : String Level : Any This is a very simple text encryption routine. It isn't particularly hard to crack, but will provide a basic level of security for undemanding applications. The same routine can be used either to encrypt or decrypt text. The original text may contain any character below CHR$(128), as may the password. The resulting text will be printable, if bizarre (all characters will be above CHR$(127)), and may be used with sequential files. This routine is potentially less secure than the Cipher routine (see). I'd suggest using a long password composed of an unlikely string of characters, e.g. "#*@@!A^%x{.'". CipherP St$, Password$ St$ string to encrypt or decrypt Password$ password ------- St$ encrypted or decrypted string Name : ClearArea (Clear a screen Area) Class : Display Level : Clone This routine clears an area of the screen to a specified color. The clearing is done by removing random characters until the area is totally clear. ClearArea TopRow%, LeftCol%, BottomRow%, RightCol%, Attr%, Fast% TopRow% top row of area to clear LeftCol% left column of area to clear BottomRow% bottom row of area to clear RightCol% right column of area to clear Attr% color/attribute to clear to Fast% whether to use fast displays (may cause snow on CGAs) (0 no) Name : Clock (Clock) Class : Display / Time Level : Clone This routine allows you to turn a visible time display on or off. When on, the time will be continuously displayed at a selected location while your program continues processing. The clock is managed as a background process, in effect doing some simple multitasking. You should turn the clock off before you terminate your program, including any time you execute another program with RUN. The clock can be safely kept on when you SHELL to another program, however, as long as you can be sure that control will return to your program when the other is done. The clock must also be turned off if you change any of its parameters with the ClockSet routine (see). The clock will only be visible when the display is in text mode. The use of PLAY or SOUND statements may shut off the clock, depending on your version of the BASIC compiler. Clock DisplayOn% DisplayOn% whether to display the clock (0 if no) Name : ClockSet (Clock Settings) Class : Display / Time Level : Clone The ClockSet routine is used in conjunction with Clock (see). It should only be used when the clock is turned off. This routine allows you to set 12-hour or 24-hour time, whether to display the seconds or not, how often to update the clock display (in 1/18th seconds; 9 is usually the best choice), where to display the clock and in what color, and whether to use flicker-free displays (needed for cheap CGAs only). The defaults are 12-hour time, display seconds, put the time (in white on black) in the upper right corner, and display quickly (may flicker on some CGAs). ClockSet Hours24%, Seconds%, Updates%, Row%, Column%, Attr%, Fast% Hours24% whether to display 24-hour time (0 if no) Seconds% whether to display seconds (0 if no) Updates% display update frequency in 1/18th seconds (9 is usually best) Row% row on which to display the clock Col% column at which to display the clock Attr% color/attribute to use (see CalcAttr) Fast% whether to use fast mode (nonzero if so; may cause snow on CGAs) Name : CloseA (Close Archive) Class : Disk / Time Level : DOS This routine closes an archive opened by FindFirstA or FindNextA. It must be used when you are done searching the archive. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA CloseA Name : ClrCols (Clear Columns) Class : Display Level : BIOS This routine clears the current row between the specified columns, inclusive. It does not affect the cursor position. ClrCols StartCol%, EndCol% StartCol% starting column EndCol% ending column Name : ClrEOL (Clear to End Of Line) Class : Display Level : BIOS This routine clears from the cursor to the end of the line, inclusive. It does not affect the current cursor position. ClrEOL Name : ClrEOP (Clear to End Of Page) Class : Display Level : BIOS This routine clears from the cursor to the end of the display, inclusive. It does not affect the current cursor position. ClrEOP Name : ClrSOL (Clear to Start Of Line) Class : Display Level : BIOS This routine clears from the start of the line to the cursor, inclusive. It does not affect the current cursor position. ClrSOL Name : ClrKbd (Clear Keyboard buffer) Class : Input Level : DOS ClrKbd clears the keyboard buffer, discarding any keys that may be waiting. This is a good idea for situations where an unexpected input is made and you don't want to chance it being answered accidentally by keys that were typed beforehand-- for instance, in the event of an error or other condition where it is important that the user see a message or take an action before pressing a key. ClrKbd Name : ClrSOP (Clear to Start Of Page) Class : Display Level : BIOS This routine clears from the start of the display to the cursor, inclusive. It does not affect the current cursor position. ClrSOP Name : CopyFile (Copy a File) Class : Disk Level : DOS This works like the DOS COPY command, although it does not allow wildcards. One file is copied to another, retaining the same date and time. Full path specifications are supported, including drive and subdirectory specs. See also FileCopy, which supports wildcards. CopyFile FromFile$, ToFile$, ErrCode% FromFile$ name of file to copy ToFile$ name of new file to create ------- ErrCode% 0 if no error, else DOS Error Name : CPrintScreen1 (CGA Print Screen [SCREEN 1]) Class : Display / Printer Level : Clone This routine dumps a SCREEN 1 display (CGA 320x200) to the printer. It uses the stdprn device (normally PRN or LPT1) by default, although this can be altered with the PrtSwap routine. CPrintScreen1 Name : CPrintScreen2 (CGA Print Screen [SCREEN 2]) Class : Display / Printer Level : Clone This routine dumps a SCREEN 2 display (CGA 640x200) to the printer. It uses the stdprn device (normally PRN or LPT1) by default, although this can be altered with the PrtSwap routine. CPrintScreen2 Name : CRC (calculate CRC) Class : String / Serial Level : Any This routine has become obsolete; the CRC1 routine is much faster. However, CRC is still included for backwards compatibility. This routine calculates a complex 16-bit checksum, called a Cyclical Redundancy Check (or CRC) on a string. The results are compatible with Xmodem and Ymodem CRC routines. The CRC provides a fairly reliable check of what characters are contained in the string. See also Checksum. If you are using this routine for Xmodem or Ymodem, note that the string should be padded with two null characters before calculating a "send" CRC: St$ = St$ + STRING$(2, 0). On receive, you should calculate the CRC on the entire data block, plus the received CRC; if the block was received correctly, the calculated CRC will be zero in both lsb and msb. Although Intel notation uses "lsb, msb" order, the Xmodem/Ymodem CRC uses the opposite format, which is why the parameters are ordered in this fashion. CRC St$, CRCmsb%, CRClsb% St$ string to process ------- CRCmsb% most significant byte of CRC CRClsb% least significant byte of CRC Name : CRC1 (calculate CRC) Class : String / Serial Level : Any This routine calculates a complex 16-bit checksum, called a Cyclical Redundancy Check (or CRC) on a string. The results are compatible with Xmodem and Ymodem CRC routines. The CRC provides a fairly reliable check of what characters are contained in the string. See also Checksum. Note that CRC1 does not work like the older CRC routine. You should not pad outgoing strings with a STRING$(2, 0) sequence. Although Intel notation uses "lsb, msb" order, the Xmodem/Ymodem CRC uses the opposite format, which is why the parameters are ordered in this fashion. CRC St$, CRCmsb%, CRClsb% St$ string to process ------- CRCmsb% most significant byte of CRC CRClsb% least significant byte of CRC Name : Crunch (Crunch repeated characters) Class : String Level : Any It was hard to decide on a name for this routine, and I don't know if I've done the best job. What Crunch does is to eliminate repeated sequences of the same character. For instance, if you gave it "This is a test" and asked it to crunch spaces, it would return "This is a test". I use this to filter information from the COMMAND$ function, but it's a good general purpose input filter. Crunch St$, Ch$, StLen% St$ = LEFT$(St$, StLen%) St$ string to be processed Ch$ character to crunch out of the string ------- St$ crunched string StLen% length of the crunched string Name : CtrlKey (Control Key) Class : Input Level : Any This routine works in conjunction with a key input routine, such as INKEY$ or the CheckKey and GetKey routines. Given the ASCII code of a key, CtrlKey returns the associated key letter, if any. For instance, it returns "A" if you pass it ASCII code 1, because that code represents Ctrl-A. CtrlKey ASCIICode%, Ky$ ASCIICode% ASCII code of the key ------- Ky$ associated key letter ("" if none) Name : CursorInfo (Cursor Information) Class : Input Level : Clone While BASIC allows you to set the size and shape of the cursor with LOCATE, it's fairly hazardous to do so. There is no way to find out the maximum size of the cursor, so your cursor may end up a peculiar shape on some adapters. If you change the cursor size or visibility in a subprogram, you may be screwing up the main program. CursorInfo offers a solution to these problems. It returns the current cursor visibility and size, plus the maximum size possible with the current video adapter. CursorInfo Visible%, StartLine%, EndLine%, MaxLine% ------- Visible% whether the cursor is visible (0 no, 1 yes) StartLine% starting scan line of cursor EndLine% ending scan line of cursor MaxLine% maximum possible scan line for cursor (minimum is always zero) Name : CWindowManager (CGA Window Manager) Class : Display Level : Clone CWindowManager displays a pop-up window on a CGA graphics screen. It is intended for SCREEN 1, although it can be used on SCREEN 2 as well (it will still have 40 columns and will display shades rather than colors). The window may have any of a variety of frames, a title, or a shadow, and it may appear instantly or "grow" onto the screen. These are the available frame types: 0 no frame 1 single lines 2 double lines 3 single horizontal, double vertical lines 4 double horizontal, single vertical lines 5 block graphic lines Options for growing windows are as follows: -1 grow as fast as possible 0 pop onto the screen 1+ grow with a specified delay in milliseconds (15 works well for me) Note that this routine is different from its ProBas equivalent in a number of respects. The grow delay time is different. Growing is done more smoothly. The shadow and title parameters are not changed by this routine. A new frame type (5) was added. If a title is too long, it is truncated instead of being ignored completely. Using a -1 as the title foreground color will not turn off the title; instead, use a null title string. CWindowManager TopRow%, LeftCol%, BottomRow%, RightCol%, Frame%, Fore%, Back%, Grow%, Shade%, TFore%, Title$, Fast% TopRow% top row of window LeftCol% left column of window BottomRow% bottom row of window RightCol% right column of window Frame% frame type (see above) Fore% frame foreground color Back% frame background color Grow% window growing option (see above) Shade% window shadow option (0 for none) TFore% title foreground color Title$ window title ("" if none) Fast% whether to use fast mode (0 if no, to avoid snow on CGAs) Name : DataSeg (Data Segment) Class : Memory Level : Any It's rare that you need to know the data segment used by BASIC, but it does happen. DataSeg tells you that value. This is the segment used by (near) strings, static arrays (except in the QuickBASIC environment), some COMMON data, BASIC internal variables and so forth. It is also the area specified by a plain "DEF SEG", though not (usually) by "DEF SEG=xxxx". DataSeg DSeg% ------- DSeg% data segment for BASIC Name : Date2Int (Date to Integer) Class : Time Level : Any This routine compresses a date into a single integer. Note that this integer is not in a format that lends itself to simple computation-- you cannot subtract one from another to find out the length of time between them. However, as long as the year is in the range 1980-2042, you can compare the two integers to see if one date is before or after another. You may express the year as either a two-digit or four-digit number. The ProBas and PBClone versions of this routine do not work the same way in regards to the year. ProBas assumed that any two-digit year was in the 1900s. In contrast, PBClone assumes that years 80-99 should be converted to 1980-1999 and that 0-79 should be converted to 2000-2079. I consider the PBClone method more appropriate, with the turn of the century moving closer. The date format used does not allow dates before 1980 anyway, so nothing is being lost by this change. Date2Int MonthNr%, Day%, Year%, IntDate% MonthNr% month number (1-12) Day% day (1-31) Year% year (1980-2079; see above for two-digit year handling) ------- IntDate% date compressed into an integer Name : DateA2R (Date Actual to Relative) Class : Time Level : Any This routine converts an actual date to a relative date, expressed as a number of days. This allows you to compare dates, find out what the date will be in a given number of days (or what it was a given number of days ago), see how many days passed between two dates, and so forth. I've frequently seen routines of this nature called "Julian date" routines. I'm not sure where that nomenclature originated, as it has nothing to do with the Julian calendar. Most of these routines rely on approximations through floating point math, and may or may not handle leap years and centuries appropriately. The DateA2R routine takes no such shortcuts and may be relied upon to return accurate results. DateA2R MonthNr%, DayNr%, YearNr%, RelDate& MonthNr% month number (1-12) DayNr% day number (1-31) YearNr% year number (1900 on; years <100 will be assumed 20th century) ------- RelDate& relative date Name : DateN2S (Date Numbers to String) Class : Time Level : Any / DOS Many of the PBClone routines return the date as a set of numbers. This routine provides an easy way to convert those numbers into string form. The date format used (year length and delimiter) will be based on the string which you pass to the routine. For instance, "xx-xx-xxxx" will return a date like "11-26-1990", whereas "xx.xx.xxxx" would return "11.26.1990", and "xx/xx/xx" would return "11/26/90". If you pass zeroes for the MonthNr%, Day%, and Year% values, the current date will be returned in the format that you specified. The ProBas and PBClone versions of this routine do not work the same way in regards to the year. ProBas assumed that any two-digit year was in the 1900s. In contrast, PBClone assumes that years 80-99 should be converted to 1980-1999 and that 0-79 should be converted to 2000-2079. DateSt$ = "xx-xx-xxxx" DateN2S MonthNr%, Day%, Year%, DateSt$ MonthNr% month Day% day Year% year ------- DateSt$ date string. Init to 8 or 10 chars including delimiters (see above). Name : DateR2A (Date Relative to Actual) Class : Time Level : Any This is the opposite of the DateA2R routine-- it takes a "relative" date and converts it back to the usual form. DateR2A MonthNr%, DayNr%, YearNr%, RelDate& RelDate& relative date ------- MonthNr% month number (1-12) DayNr% day number (1-31) YearNr% year number (1900 on) Name : DateS2N (Date String to Numbers) Class : Time Level : Any Many of the PBClone routines need to be passed the date as a set of numbers. This routine provides an easy way to convert a date from string form into numbers. You may use either "xx/xx/xx" or "xx-xx-xxxx" form to specify the date (the string length is important, but the delimiter and contents of the string are ignored). The ProBas and PBClone versions of this routine do not work the same way in regards to the year. ProBas assumed that any two-digit year was in the 1900s. In contrast, PBClone assumes that years 80-99 should be converted to 1980-1999 and that 0-79 should be converted to 2000-2079. DateS2N MonthNr%, Day%, Year%, DateSt$ DateSt$ date string. Init to 8 or 10 characters (see above). ------- MonthNr% month Day% day Year% year Name : DCal (Direct-to-memory Calendar) Class : Time Level : Any This routine draws a calendar for a specific month and year. The results are placed in an array which can be displayed using ScrRest or the other PBClone routines to restore a screen image. You must supply an integer array large enough to hold the image generated by DCal, which expects a 25x80 screen. DIM Scrn%(1 TO 2000) will do it. If you supply a null date, the current date will be used. DCal Scrn%(), CalDate$ Scrn%() array to hold screen image CalDate$ date for the calendar Page% ignored Fast% ignored Name : DCalendar (Direct-to-memory Calendar) Class : Time Level : Clone This routine displays a calendar for a specific month and year. It waits for input and acts accordingly, allowing the user to move to different dates via the arrow keys or by entering the date directly. The bottom row of the screen gives a list of the available key commands. Screen handling is largely done by writing to an array, then dumping the entire array to the display with DScrRest. This provides for very smooth displays. You must supply an integer array large enough to hold the image generated by DCalendar, which expects a 25x80 screen. DIM Scrn%(1 TO 2000) will do it. Only text mode is supported by this routine. If you supply a null date, the current date will be used. DCalendar Scrn%(), CalDate$, Page%, Fast% Scrn%() array to hold screen image CalDate$ date for the calendar Page% page on which to display (normally zero) Fast% whether to use fast mode (nonzero if so; may cause snow on CGAs) Name : DClear (Direct-to-memory Clear) Class : Display Level : Any The DClear routine allows you to clear a text-mode display. This routine does not necessarily work on the display itself. Instead, it allows you to specify the memory location (segment and offset) of the "screen", which may be an actual screen, a saved screen in an array, a multitasker's virtual screen, etc. Among other things, this makes it easy to work with two displays at once: use a segment of &HB000 for the mono display and &HB800 for the color display (the offset in each case is zero). DClear DSeg%, DOfs%, Attr% DSeg% segment of "screen" memory DOfs% offset of "screen" memory Attr% color/attribute to use (see CalcAttr) Name : DClearSS (Direct-to-memory Clear for Specified Size) Class : Display Level : Any Like the CLS statement, this routine allows you to clear a text display. However, rather than clearing the actual screen, DClearSS clears a screen that is stored in an array. This allows you to design a screen in memory, then flash it onto the display using PutScreen or a similar routine. This routine is designed for a text screen of any specified size. DClearSS DSeg%, DOfs%, Attr%, Rows%, Columns% DSeg% segment of the array that holds the screen DOfs% offset of the array that holds the screen Attr% color/attribute to use (see CalcAttr) Rows% length of the screen Columns% width of the screen Name : Dec2Any (Decimal to Any base) Class : Numeric Level : Any This routine converts a normal integer to a number in any base. It works like the HEX$ function in BASIC, but rather than working only in hexadecimal (base 16), it can be used for binary, octal, or almost anything else. The result will be right-justified in the string you provide. If you use zeroes, this allows you to ignore the NumberLen% spec and just trim the string to the desired length, leaving nothing worse than possible leading zeroes. The length needed by the return string will vary according to the number, with a maximum length depending on the number base chosen. For integers, this will be at most 16 characters (worst case: base 2 or binary). Number$ = STRING$(16, "0") Dec2Any DecimalNr%, NrBase%, Number$, NumberLen% Number$ = RIGHT$(Number$, NumberLen%) DecimalNr integer to convert to another base NrBase% desired number base (2-31) ------- Number$ resulting number in desired base (init to at least 16 chars) NumberLen% length of the result (-1 if insufficient space in string) Name : Delay (Delay for seconds) Class : Time Level : Clone This routine delays for a given number of seconds. The timing will be the same from an 8088 PC through an 80486 AT-- it's entirely independent of the processor. See also Delay18th. Delay Seconds% Seconds% number of seconds for which to delay Name : Delay18th (Delay for 1/18th seconds) Class : Time Level : Clone This routine delays for a given number of 18ths of seconds. The timing will be the same from an 8088 PC through an 80486 AT-- it's entirely independent of the processor. See also Delay. Delay WaitTime% WaitTime% number of 18ths of seconds for which to delay Name : DelayV (Delay based on Video timing) Class : Time Level : Clone This routine delays for a given number of milliseconds. The timing is based on a signal from the video adapter and may vary somewhat depending on the adapter. The delay is largely independent of the cpu type and speed, however. For anyone unfamiliar with the metric system: there are 1000 milliseconds in one second. Depending on the specific display adapter, this routine may well be fairly inaccurate; it is intended for providing small delays for animation and similar purposes, not as a reliable timer. DelayV MilliSeconds% MilliSeconds% number of milliseconds for which to delay Name : DelChr (Delete Character) Class : Display Level : Clone The DelChr routine deletes the character at the specified screen location. DelChr Row%, Column% Row% row of character Column% column of character Name : DelLine (Delete Line) Class : Display Level : BIOS This routine deletes the specified row from the screen. DelLine Row%, Attr% Row% row to delete Attr% color/attribute to use on new bottom row (see CalcAttr) Name : DelFile (Delete File) Class : Disk Level : DOS This works like the DOS DEL (or ERASE) command, although it does not allow wildcards. The specified file is deleted. Full path specifications are supported, including drive and subdirectory specs. DelFile FileName$, ErrCode% FileName$ name of the file to delete ------- ErrCode% 0 if no error, else DOS Error Name : DelSub (Delete Subdirectory) Class : Disk Level : DOS This works like the DOS RD (or RMDIR) command. It does not allow wildcards. The specified subdirectory is deleted. Note that you may not delete a subdirectory that you're located in, or a subdirectory which contains files, or the root directory. DelSub SubDir$, ErrCode% SubDir$ name of the subdirectory to delete ------- ErrCode% 0 if no error, else DOS Error Name : DFRead (Direct-to-memory File Read) Class : Disk Level : DOS This routine reads data into an array from a file that was opened by FOpen or FCreate. If it wasn't possible to read it all from the file, an error code will be returned and the BytesRead% value will tell you how many bytes were actually read. DFRead Handle%, DSeg%, DOfs%, Bytes%, BytesRead%, ErrCode% Handle% handle of the file from which to read DSeg% segment of the array into which to read the file DOfs% offset of the array into which to read the file Bytes% number of bytes to read ------- BytesWrit% number of bytes actually read from the file (if error) ErrCode% error code: 0 if no error, else DOS Error Name : DFWrite (Direct-from-memory File Write) Class : Disk Level : DOS This routine writes data from an array to a file that was opened by FOpen or FCreate. If it wasn't possible to write it all to the file, an error code will be returned and the BytesWrit% value will tell you how many bytes were actually written. DFWrite Handle%, DSeg%, DOfs%, Bytes%, BytesWrit%, ErrCode% Handle% handle of the file to which to write DSeg% segment of the data to write to the file DOfs% offset of the data to write to the file Bytes% number of bytes to write ------- BytesWrit% number of bytes actually written to the file (if error) ErrCode% error code: 0 if no error, else DOS Error Name : DGClear (Direct-to-memory Graphics Clear) Class : Display Level : Any This routine works like the CLS statement, clearing a CGA graphics display. However, rather than clearing the actual screen, DClearSS clears a screen that is stored in an array. This allows you to design a screen in memory, then flash it onto the display using GrafRest. This routine is designed for use with SCREEN 1 or SCREEN 2 (CGA graphics). DGClear DSeg%, DOfs%, Colour% DSeg% segment of the array that holds the screen DOfs% offset of the array that holds the screen Colour% color to use Name : DGetRec (Direct-from-memory Get Record) Class : String Level : Clone The DGetRec routine allows you to get a string from a specified area of memory (numeric array, BIOS data area, display memory, or whatever). The string should be initialized to the desired record length in advance. This works somewhat like an array of fixed length strings or a random file, treating memory as a contiguous series of records of a specified length. DGetRec DSeg%, DOfs%, RecNr%, St$ DSeg% segment of the array to read from DOfs% offset of the array to read from RecNr% record number (starting at 1) ------- St$ returned string. Init to the record length (see above). Name : DGetScreen (Direct-to-memory Get Screen image) Class : Display Level : Clone This routine saves any portion of the display to an array. Only text modes are supported. If your program uses multiple display pages, you can get an image from any of those pages. A special "slow" mode is supported for the CGA, to prevent flickering (a problem only with some CGAs). The size of the integer array needed to store a specific area of the screen can be calculated using the CalcSize routine (see). The GetScreen routine works the same way as this, but has a simpler calling convention. Also, if you wish to save the entire screen, you may find ScrSave easier. DGetScreen DSeg%, DOfs%, TopRow%, LeftCol%, BotRow%, RightCol%, Page%, Fast% DSeg% segment of the array in which to store the image DOfs% offset of the array in which to store the image TopRow% top row of the desired screen area LeftCol% left column of the desired screen area BotRow% bottom row of the desired screen area RightCol% right column of the desired screen area Page% page from which to get the display area Fast% whether to use fast mode (nonzero if so; else slow, for some CGAs) Name : DGetSt (Direct-from-memory Get String) Class : String Level : Clone The DGetSt routine allows you to get a string from a specified area of memory (numeric array, BIOS data area, display memory, or whatever). The string should be initialized to the desired length in advance. You may specify an additional offset from the initial location, which itself is specified as a segment and an offset. The second offset begins with position 1. The combined total of the two offsets must be under 65,536 at the moment. I'll remove that restriction at a later time. With normalized segment and offset specifications, which is usually the case, this allows you to specify a number from 1-65,521 for the second offset. DGetSt DSeg%, DOfs%, Posn&, St$ DSeg% segment of the array to read from DOfs% offset of the array to read from Posn& location relative to the start of the array ------- St$ returned string. Init to the number of chars desired (see above). Name : DGQPrint (Direct-to-memory Graphics Quick Print) Class : Display Level : Any This is a simple high-speed replacement for the PRINT statement which works on a CGA virtual graphics screen (SCREEN 2). It does not interpret control codes or support graphics characters (ASCII 128-255). DGQPrint allows you to display to a CGA even if it isn't the active display (use a segment of &HB800 and offset of 0). Its intended use, however, is to display to a virtual screen kept in an array or other memory area. The results can then be displayed using GrafRest. DGQPrint DSeg%, DOfs%, St$, Row%, Column% DSeg% segment of CGA virtual screen DOfs% offset of CGA virtual screen St$ string to display Row% row (1-25) Column% column (1-80) Name : DGXQPrint (Direct-to-memory Graphics Extended Quick Print) Class : Display Level : Any This is a simple high-speed replacement for the PRINT statement which works on a CGA virtual graphics screen (SCREEN 1). It does not interpret control codes or support graphics characters (ASCII 128-255). This routine can also be used on a SCREEN 2 display, where it will display the string in shades instead of in color (using 40 columns/row). DGXQPrint allows you to display to a CGA even if it isn't the active display (use a segment of &HB800 and offset of 0). Its intended use, however, is to display to a virtual screen kept in an array or other memory area. The results can then be displayed using GrafRest. DGXQPrint DSeg%, DOfs%, St$, Row%, Column%, Fore% DSeg% segment of CGA virtual screen DOfs% offset of CGA virtual screen St$ string to display Row% row (1-25) Column% column (1-40) Fore% foreground color (0-3) Name : DGXQPrint1 (Direct-to-memory Graphics Extended Quick Print) Class : Display Level : Any This is a high-speed replacement for the PRINT statement which works on a CGA virtual graphics screen (SCREEN 1). It does not interpret control codes. This routine can also be used on a SCREEN 2 display, where it will display the string in shades instead of in color (using 40 columns/row). DGXQPrint1 allows you to display to a CGA even if it isn't the active display (use a segment of &HB800 and offset of 0). Its intended use, however, is to display to a virtual screen kept in an array or other memory area. The results can then be displayed using GrafRest. DGXQPrint1 DSeg%, DOfs%, St$, Row%, Column%, Fore%, Back% DSeg% segment of CGA virtual screen DOfs% offset of CGA virtual screen St$ string to display Row% row (1-25) Column% column (1-40) Fore% foreground color (0-3) Back% background color (0-3) Name : DInput (Dollar Input) Class : Input Level : Clone This routine provides formatted input of a dollar amount. You specify the format and an initial value (may be zero). You may also specify whether to allow negation-- if so, the user may press the "-" key to toggle the number between negative and positive. The numeric keypad will automatically be locked into the numeric state. Since the decimal point is implicit, the "." key functions as a delete or backspace operation, for convenient one-handed data entry and correction. The dollar amount is kept in a long integer as a number of pennies, to avoid the possibility of round-off errors which might result from use of floating point math. The results are returned to you both as a long integer and as a formatted number. The format string works just like a PRINT USING format string. Editing is not as flexible as for SInput, but is quite adequate. The SInputSet routines will work for DInput as well as SInput. The ExitCode% returned is the same as for SInput, but left and right arrows may also be returned. DInput Format$, St&, St$, MinusOk%, Attr%, ExitCode% Format$ numeric format (just like PRINT USING format); e.g. "$$##,###.##-" St& dollar amount (in pennies) MinusOk% whether negation is allowed (0 if no) Attr% color/attribute to use (see CalcAttr) ------- St& dollar amount (in pennies) St$ formatted dollar amount ExitCode% key used to exit (ASCII code if positive, scan code if negative) Name : DiskStat (Disk Statistics) Class : Disk Level : DOS DiskStat gives you statistics on the memory usage of a specified disk drive: the total number of clusters, the number of available or free clusters, the number of sectors per cluster, and the number of bytes per sector. From this information, you can determine how much total disk space there is, how much space is left and how much is used, the size of a cluster, et al. A few formulas for you: ClusterSize% = BytesPerSec% * SecsPerClus% FreeSpace& = FreeClus& * ClusterSize% TotalSpace& = TotalClus& * ClusterSize% UsedSpace& = TotalSpace& - FreeSpace& A "cluster" is the minimum amount of disk space that can be allocated at a time. A typical cluster size for a medium-sized hard drive is 2048 bytes, which means that any file from 1-2048 bytes in length is actually taking up a full 2048 bytes on the disk. Large cluster sizes improve file access times but can waste a lot of disk space. DiskStat Drive$, FreeClus&, TotalClus&, BytesPerSec%, SecsPerClus% Drive$ letter of the drive to examine ------- FreeClus& number of free or available clusters TotalClus& total number of clusters BytesPerSec% bytes per sector SecsPerClus% sectors per cluster (-1 if bad drive, open drive door, etc) Name : Dissolve (Dissolve) Class : Display Level : Clone Like CLS, but a bit more fancy, this routine provides an interesting way to clear the screen. See also FadeOut. This routine may cause heavy flickering on some CGA displays. Dissolve Attr% Attr% color/attribute to which to clear (see CalcAttr) Name : DMPrint (DOS Message Print) Class : Display Level : DOS This routine is similar to PRINT, but goes through DOS output services, which allows your program to support output redirection, filters, CTTY and other handy things. See DOSInkey for a DOS input service. Note that the use of DMPrint means that you should avoid using BASIC display handling (CLS, INPUT, LINE INPUT, PRINT, LOCATE, CSRLIN, POS, etc). Instead, you should use ANSI escape sequences to control the display. This requires that an ANSI driver (like ANSI.SYS, DVANSI.SYS, NANSI.SYS, or ZANSI.SYS) be installed on your system. See your DOS manual for details on ANSI sequences, or grab the documentation on ANSI from one of your friendly local BBSes. It is -possible- to use BASIC display handling in conjunction with DMPrint, but that tends to defeat the purpose of using DMPrint in the first place. Note that the DMPrint routine does not add a carriage return/linefeed to the end of a string. If you want that, add CHR$(13) + CHR$(10) to the end of the string. DMPrint St$ St$ string to display Name : DOSClrEol (DOS Clear to End Of Line) Class : Display Level : DOS This routine clears from the cursor position to the end of the row using DOS output functions. It requires that ANSI.SYS or another ANSI driver be installed. DOSClrEol Name : DOSCls (DOS Clear Screen) Class : Display Level : DOS This routine clears the screen using DOS output functions. It requires that ANSI.SYS or another ANSI driver be installed. DOSCls Name : DOSColor (DOS Color) Class : Display Level : DOS This routine sets the screen colors using DOS output functions. It requires that ANSI.SYS or another ANSI driver be installed. DOSColor Fore%, Back% Fore% foreground color Back% background color Name : DOSErrM$ (DOS Error Message) Class : Miscellaneous Level : DOS Of the many PBClone routines that return error codes, most simply pass the code back from DOS without any processing. You can see what the codes mean by checking the chart in PBClone.DOC, or it may be more convenient to use DOSErrM$ instead. This routine returns a short text description of the error in question. ErrMsg$ = DOSErrM$(ErrCode%) ErrCode% error code to translate ------- ErrMsg$ brief explanation of the error Name : DOSInkey (DOS INKEY$) Class : Input Level : DOS This routine is similar to INKEY$, but goes through DOS input services, which allows your program to support input redirection, filters, CTTY and other handy things. See DMPrint for a DOS output service. See also DOSInky$. DOSInkey CharCode%, CharType% ------- CharType% 0 if no key, 1 if normal key, 2 if extended key CharCode% ASCII code if normal key, scan code if extended key Name : DOSInky$ (DOS INKEY$) Class : Input Level : DOS This routine works just like INKEY$, but goes through DOS input services, which allows your program to support input redirection, filters, CTTY and other handy things. See DMPrint for a DOS output service. See also DOSInkey. ky$ = DOSInky$ ------- ky$ key, if any was waiting (0-2 characters per key, like INKEY$) Name : DOSInt% (DOS Interrupt) Class : Miscellaneous Level : DOS This routine provides you with easy access to DOS functions via INT 21H, the major DOS interrupt. It works like the CALL INTERRUPT routines provided with QuickBASIC but is easier to use, at the expense of some flexibility. CAUTION: This routine works directly with DOS, bypassing most of BASIC's safety precautions. Possible chaos may result if you don't know what you're doing! A few specific caveats: 1) Do Not use this routine to exit your program or execute another. BASIC needs to clean up after itself before these tasks, and bypassing its handling is liable to make the system unstable at best. 2) If you expect to use a string or array as a buffer, make sure it is long enough to handle the maximum amount of information anticipated. Strings and arrays can move about in memory, so be sure to get their addresses Just Before using DOSInt%. If you wish to specify BASIC's data segment for DS, you can find out what that is using the DataSeg routine (q.v.). CarryFlag% = DOSInt%(AX%, BX%, CX%, DX%, DS%) AX% desired setting of the AX register BX% desired setting of the BX register CX% desired setting of the CX register DX% desired setting of the DX register DS% desired setting of the DS and ES registers ------- AX% returned setting of the AX register BX% returned setting of the BX register CX% returned setting of the CX register DX% returned setting of the DX register DS% returned setting of the DS and ES registers CarryFlag% returned carry flag (0 if no error, else AX is error code) Name : DOSLocate (DOS Locate) Class : Display Level : DOS This routine sets the cursor position using DOS output functions. It requires that ANSI.SYS or another ANSI driver be installed. Note that many ANSI drivers do not fully support EGA or VGA modes in that they are limited to a maximum of 25 rows. DOSLocate Row%, Column% Row% row Column% column Name : DPutRec (Direct-to-memory Put Record) Class : String Level : Clone The DPutRec routine allows you to put a string into a specified area of memory (numeric array, BIOS data area, display memory, or whatever). The string should be initialized to the desired record length in advance. This works somewhat like an array of fixed length strings or a random file, treating memory as a contiguous series of records of a specified length. DPutRec DSeg%, DOfs%, RecNr%, St$ DSeg% segment of the array to write into DOfs% offset of the array to write into RecNr% record number (starting at 1) St$ string to write. Init to the record length (see above). Name : DPutScreen (Direct-from-memory Put Screen) Class : Display Level : Clone This routine restores a portion of the display (which was saved to an array by DGetScreen or GetScreen) to the screen. Only text modes are supported. If your program uses multiple display pages, you can put the image onto any of those pages. A special "slow" mode is supported for the CGA, to prevent flickering (a problem only with some CGAs). The PutScreen routine works the same way as this, but has a simpler calling convention. Also, if you wish to restore the entire screen, you may find ScrRest easier (see). DPutScreen DSeg%, DOfs%, TopRow%, LeftCol%, BotRow%, RightCol%, Page%, Fast% DSeg% segment of the array from which to restore the image DOfs% offset of the array from which to restore the image TopRow% top row of the desired screen area LeftCol% left column of the desired screen area BotRow% bottom row of the desired screen area RightCol% right column of the desired screen area Page% page on which to restore the display Fast% whether to use fast mode (nonzero if so; else slow, for some CGAs) Name : DPutSt (Direct-to-memory Put String) Class : String Level : Clone The DPutSt routine allows you to put a string into a specified area of memory (numeric array, BIOS data area, display memory, or whatever). You may specify an additional offset from the initial location, which itself is specified as a segment and an offset. The second offset begins with position 1. The combined total of the two offsets must be under 65,536 at the moment. I'll remove that restriction at a later time. With normalized segment and offset specifications, which is usually the case, this allows you to specify a number from 1-65,521 for the second offset. DPutSt DSeg%, DOfs%, Posn&, St$ DSeg% segment of the array to write to DOfs% offset of the array to write to Posn& location relative to the start of the array St$ string to write into memory Name : DRecDel (Direct-to-memory Record Deletion) Class : Array management Level : Any This routine allows you to delete an item from an array. The item may consist of one or more array elements. The size of the array isn't actually changed, but the array elements are moved as if a deletion took place. DRecDel DSeg%, DOfs%, RecNr%, RecLen%, Records% DSeg% segment of the array DOfs% offset of the array RecNr% record/element number (starting at 1) RecLen% record/element length in bytes Records% total number of records/elements in the array Name : DRecIns (Direct-to-memory Record Insertion) Class : Array management Level : Any This routine allows you to insert an item into an array. The item may consist of one or more array elements. The size of the array isn't actually changed, but the array elements are moved as if an insertion took place. You must of course make sure that the array is DIMed large enough to handle this. DRecIns DSeg%, DOfs%, RecNr%, RecLen%, Records% DSeg% segment of the array DOfs% offset of the array RecNr% record/element number (starting at 1) RecLen% record/element length in bytes Records% total number of records/elements in the array Name : DRecolor (Direct-to-memory Recolor) Class : Display Level : Any The DRecolor routine changes all text in one color to another color. It works only in text modes. The colors are specified as attributes (see CalcAttr). This routine does not necessarily work on the display itself. Instead, it allows you to specify the memory location (segment and offset) of the "screen", which may be an actual screen, a saved screen in an array, a multitasker's virtual screen, etc. Among other things, this makes it easy to work with two displays at once: use a segment of &HB000 for the mono display and &HB800 for the color display (the offset in each case is zero). DRecolor DSeg%, DOfs%, OldAttr%, NewAttr% DSeg% segment of "screen" memory DOfs% offset of "screen" memory OldAttr% color to be changed NewAttr% color to which to change Name : DRecolorArea (Direct-to-memory Recolor Area) Class : Display Level : Clone The DRecolorArea routine changes a specified area of the screen to a specified color. It works only in text modes. The color is specified as an attribute (see CalcAttr). One of the more common applications for this routine is marking an area of the screen, e.g. menu highlight bars. DRecolorArea DSeg%, DOfs%, TopRow%, LeftCol%, BottomRow%, RightCol%, Attr% This routine does not necessarily work on the display itself. Instead, it allows you to specify the memory location (segment and offset) of the "screen", which may be an actual screen, a saved screen in an array, a multitasker's virtual screen, etc. Among other things, this makes it easy to work with two displays at once: use a segment of &HB000 for the mono display and &HB800 for the color display (the offset in each case is zero). DSeg% segment of "screen" memory DOfs% offset of "screen" memory TopRow% top row of area to recolor LeftCol% left column of area to recolor BottomRow% bottom row of area to recolor RightCol% right column of area to recolor Attr% desired color Name : DriveSpace& (Drive Space free) Class : Disk Level : DOS This routine tells you how many bytes are free on a specified disk drive. BytesFree& = DriveSpace&(Drive$) Drive$ letter of the drive to examine ------- BytesFree& free bytes on the specified drive, or -1 if bad drive or disk error Name : DrvSpaceL (Drive Space free as Long integer) Class : Disk Level : DOS This routine tells you how many bytes are free on a specified disk drive. See also DriveSpace, a function-type version of this routine. DrvSpaceL Drive$, BytesFree& Drive$ letter of the drive to examine ------- BytesFree& free bytes on the specified drive, or -1 if bad drive or disk error Name : DrvType (Drive Type) Class : Disk Level : DOS 3.1+ The DrvType routine tells you whether a specified drive is fixed or removeable, and whether it is local or remote (network drive). DrvType Drive$, Removeable%, Remote%, ErrCode% Drive$ letter of the drive to examine ------- Removeable% whether the disk in the drive can be removed (0 if no) Remote% whether this is a remote drive (0 if no) ErrCode% error code: 0 if none, else bad DOS version Name : DScrRest (Direct-from-memory Screen Restore) Class : Display Level : Clone The DScrRest routine restores a display that was saved using ScrSave or a similar routine. It only works in text modes. See also ScrRest. DScrRest DSeg%, DOfs%, Page%, Fast% DSeg% segment of info to restore to the screen DOfs% offset of info to restore to the screen Page% page on which to restore the display Fast% whether to use fast mode (nonzero if so; may cause snow on CGAs) Name : DScrSave (Direct-from-memory Screen Save) Class : Display Level : Clone The DScrSave routine saves the display to an array or other storage area. Only text modes are supported. For an 80x25 display, the array must hold 4,000 bytes (4,000 string characters or 2,000 integers). See also ScrSave. DScrSave DSeg%, DOfs%, Page%, Fast% DSeg% segment of place to store the display DOfs% offset of place to store the display Page% page from which to get the display Fast% whether to use fast mode (nonzero if so; may cause snow on CGAs) Name : DTR (Data Terminal Ready signal) Class : Serial Level : Clone Just as IBM provided the standard for personal computers, Hayes provided the standard for modem commands. Unfortunately, the command method of dropping carrier (hanging up the phone) was badly designed, and all Hayes-compatible modems have a hard time recognizing that command under certain line conditions. Fortunately, there's a more reliable way of hanging up: the DTR serial signal. Turning this signal off will cause the modem to hang up very quickly. Most Hayes-compatible modems are factory-set to pay attention to the DTR; those that aren't can be made to do so either by flipping a hardware switch or with a special initialization command. See your modem manual for details. BASIC will drop the DTR when you CLOSE the comm port, but this isn't always a convenient way to do it. As a matter of fact, this can be a decided nuisance, so many people have patched their version of BASIC to avoid it. If you would like to do so, check your local BBS for the method! With the PBClone DTR routine, you can get full control over the DTR without having to CLOSE the comm port. Note: it may be wise to include a brief delay after dropping the DTR, to give the modem a chance to react. Try Delay18th (see) with a wait of around 4. DTR CommPort%, TurnOn% CommPort% serial port number (1-4, although BASIC only handles 1-2) TurnOn% whether to raise (turn on) the DTR (0 if no) Name : DWindowManager (Direct-to-memory Window Manager) Class : Display Level : Any DWindowManager displays a pop-up window according to your specifications. The window may have any of a variety of frames, a title, or a shadow, and it may appear instantly or "grow" onto the screen. These are the available frame types: 0 no frame 1 single lines 2 double lines 3 single horizontal, double vertical lines 4 double horizontal, single vertical lines 5 block graphic lines These are the available shadows: -3 transparent shadow on the right -2 transparent shadow on the left -1 solid black shadow on the left 0 no shadow 1+ shadow attribute (use CalcAttr) for a colored shadow Options for growing windows are as follows: -1 grow as fast as possible 0 pop onto the screen 1+ grow with a specified delay in milliseconds (15 works well for me) Note that this routine is different from its ProBas equivalent in a number of respects. The grow delay time is different. Growing is done more smoothly. The shadow and title parameters are not changed by this routine. A new frame type (5) was added. If a title is too long, it is truncated instead of being ignored completely. Using a -1 as the title foreground color will not turn off the title; instead, use a null title string. DWindowManager DSeg%, DOfs%, TopRow%, LeftCol%, BottomRow%, RightCol%, Frame%, Fore%, Back%, Grow%, Shade%, TFore%, Title$ This routine does not necessarily work on the display itself. Instead, it allows you to specify the memory location (segment and offset) of the "screen", which may be an actual screen, a saved screen in an array, a multitasker's virtual screen, etc. Among other things, this makes it easy to work with two displays at once: use a segment of &HB000 for the mono display and &HB800 for the color display (the offset in each case is zero). DSeg% segment of "screen" memory DOfs% offset of "screen" memory TopRow% top row of window LeftCol% left column of window BottomRow% bottom row of window RightCol% right column of window Frame% frame type (see above) Fore% frame foreground color Back% frame background color Grow% window growing option (see above) Shade% window shadow option (see above) TFore% title foreground color Title$ window title ("" if none) Name : DWindowMan2 (Direct-to-memory Window Manager) Class : Display Level : Any This routine is identical to DWindowManager but for the fact that it allows you to design your own custom window frames. Please see the description of DWindowManager for general information. These are the additional frame types: 6 custom frame composed of a single character 7 custom frame composed of the specified 7-character list: top left corner, top middle, top right corner, left middle, right middle, bottom left corner, bottom middle, bottom right corner /------------------------------------------------------------\ | A custom frame like this would be defined as frame type 7, | | with a frame string of "/-\||\-/", for instance. | \------------------------------------------------------------/ ************************************************* * On the other hand, a frame like this would be * * frame type 6, with a frame string of "*". * ************************************************* Note that this routine differs from the ProBas equivalent in that it supports full frame definitions through frame type 7 (ProBas only supports type 6). The other differences mentioned under WindowManager are also relevant. DWindowMan2 DSeg%, DOfs%, TopRow%, LeftCol%, BottomRow%, RightCol%, Frame%, FSt$, Fore%, Back%, Grow%, Shade%, TFore%, Title$ DSeg% segment of "screen" memory DOfs% offset of "screen" memory TopRow% top row of window LeftCol% left column of window BottomRow% bottom row of window RightCol% right column of window Frame% frame type (see above) FSt$ frame definition string (see above) Fore% frame foreground color Back% frame background color Grow% window growing option (see above) Shade% window shadow option (see above) TFore% title foreground color Title$ window title ("" if none) Name : DWindowMan3 (Direct-to-memory Window Manager) Class : Display Level : Any This routine is identical in function to DWindowManager. The parameters are mostly passed as an array, however, instead of one by one. Please see the description of DWindowManager for general information. DWindowMan3 Parm%(), Title$ DSeg% segment of "screen" memory DOfs% offset of "screen" memory Parm%(1) top row of window Parm%(2) left column of window Parm%(3) bottom row of window Parm%(4) right column of window Parm%(5) frame type (see above) Parm%(6) frame foreground color Parm%(7) frame background color Parm%(8) window growing option (see above) Parm%(9) window shadow option (see above) Parm%(10) title foreground color Title$ window title ("" if none) Name : DWindowMan4 (Direct-to-memory Window Manager) Class : Display Level : Any This is an extremely cut-down version of DWindowManager, providing no more than a simple frame generator. These are the available frame types: 0 no frame 1 single lines 2 double lines 3 single horizontal, double vertical lines 4 double horizontal, single vertical lines 5 block graphic lines Note that this routine is different from its ProBas equivalent in that a new frame type (5) is available. DWindowMan4 DSeg%, DOfs%, TopRow%, LeftCol%, BottomRow%, RightCol%, Frame%, Attr% DSeg% segment of "screen" memory DOfs% offset of "screen" memory TopRow% top row of window LeftCol% left column of window BottomRow% bottom row of window RightCol% right column of window Frame% frame type (see above) Attr% frame color/attribute (use CalcAttr) Name : DXQPrint (Direct-to-memory Extended Quick Print) Class : Display Level : Any This routine provides a rather crude, but very fast, display capability. It works like the PRINT statement in BASIC, except that it doesn't move the cursor or process control codes. It works only in text modes. This routine does not necessarily work on the display itself. Instead, it allows you to specify the memory location (segment and offset) of the "screen", which may be an actual screen, a saved screen in an array, a multitasker's virtual screen, etc. Among other things, this makes it easy to work with two displays at once: use a segment of &HB000 for the mono display and &HB800 for the color display (the offset in each case is zero). DXQPrint DSeg%, DOfs%, St$, Row%, Column%, Attr% DSeg% segment of "screen" memory DOfs% offset of "screen" memory St$ string to display Row% starting row Column% starting column Attr% color/attribute (see CalcAttr) Name : EGARest7 (EGA Restore for SCREEN 7) Class : Display Level : Clone This routine allows you to restore a SCREEN 7 (EGA, 320x200, 16 color) display that was saved using EGASave7 (see). EGARest7 DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : EGARest8 (EGA Restore for SCREEN 8) Class : Display Level : Clone This routine allows you to restore a SCREEN 8 (EGA, 640x200, 16 color) display that was saved using EGASave8 (see). EGARest8 DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : EGARest9 (EGA Restore for SCREEN 9) Class : Display Level : Clone This routine allows you to restore a SCREEN 9 (EGA, 640x350, 16 color) display that was saved using EGASave9 (see). EGARest9 DSeg1%, DOfs1%, DSeg2%, DOfs2% DSeg1% segment of storage array #1, returned by VARSEG DOfs1% offset of storage array #1, returned by VARPTR DSeg2% segment of storage array #2, returned by VARSEG DOfs2% offset of storage array #2, returned by VARPTR Name : EGASave7 (EGA Save for SCREEN 7) Class : Display Level : Clone This routine allows you to save a SCREEN 7 (EGA, 320x200, 16 color) display that can be restored using EGARest7 (see). The array used to hold the screen must contain 32,000 bytes. For an integer array, this means that you must create the array by DIM Array%(1 TO 16000). EGASave7 DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : EGASave8 (EGA Save for SCREEN 8) Class : Display Level : Clone This routine allows you to save a SCREEN 8 (EGA, 640x200, 16 color) display that can be restored using EGARest8 (see). The array used to hold the screen must contain 64,000 bytes. For an integer array, this means that you must create the array by DIM Array%(1 TO 32000). EGASave8 DSeg%, DOfs% DSeg% segment of storage array, returned by VARSEG DOfs% offset of storage array, returned by VARPTR Name : EGASave9 (EGA Save for SCREEN 9) Class : Display Level : Clone This routine allows you to save a SCREEN 9 (EGA, 640x350, 16 color) display that can be restored using EGARest9 (see). Two arrays must be used to hold the screen, for a total of 112,000 bytes. If you use integer arrays, each array must be created by DIM Array%(1 TO 28000). EGASave9 DSeg%, DOfs% DSeg1% segment of storage array #1, returned by VARSEG DOfs1% offset of storage array #1, returned by VARPTR DSeg2% segment of storage array #2, returned by VARSEG DOfs2% offset of storage array #2, returned by VARPTR Name : Elapsed (Elapsed time) Class : Time Level : Any This routine tells you the amount of time elapsed between a given starting time and ending time. The difference between the times must be less than 24 hours for the results to be meaningful. See also ElapsedTime, the FUNCTION version of this routine. Elapsed TimeStart$, TimeStop$, TimeDiff$ TimeStart$ starting time TimeStop$ ending time ------- TimeDiff$ elapsed time Name : ElapsedTime$ (Elapsed time) Class : Time Level : Any This routine tells you the amount of time elapsed between a given starting time and ending time. The difference between the times must be less than 24 hours for the results to be meaningful. See also Elapsed, the SUB version of this routine. TimeDiff$ = ElapsedTime$(TimeStart$, TimeStop$) TimeStart$ starting time TimeStop$ ending time ------- TimeDiff$ elapsed time Name : EMSBuffer (EMS Buffer size) Class : Memory Level : BIOS EMSBuffer tells you how many bytes are needed to save the state of the EMS array routines. Used in conjunction with EMSSave and EMSRest, it allows you to preserve EMS arrays across a CHAIN to another part of your program. EMSBuffer Bytes% EMSState$ = SPACE$(Bytes%) EMSSave EMSState$ ------- Bytes% bytes needed to save EMS array state Name : EMSClose (EMS Close) Class : Memory Level : BIOS The EMSClose routine is used when you are finished with an EMS array. It frees the array handle and EMS memory for other uses. If you don't close all EMS arrays before your program ends, the memory will be lost until the system is rebooted, so it is important to remember EMSClose. EMSClose ArrayHandle% ArrayHandle% handle of an EMS array Name : EMSGet (EMS Get) Class : Memory Level : BIOS This routine gets an element from an EMS array created by EMSOpen. Element numbers start at 0. Be sure to use the right numeric type for the array-- for instance, if you opened the array for SINGLE precision, use "Value!". EMSGet ArrayHandle%, ElementNr&, Value ArrayHandle% handle of an EMS array ElementNr& element number to get ------- Value value to get element into (must be correct type for array) Name : EMSOpen (EMS Open) Class : Memory Level : BIOS This routine allows you to open a block of EMS (expanded) memory which can then be accessed like a numeric array. The array size is limited only by available EMS memory (use GetLIMM to find out how much is available). You may specify any numeric type: 1 INTEGER 2 LONG or SINGLE 3 DOUBLE When the array is opened, you are returned an "array handle" which is used to access that array. Access to the array is done via EMSGet and EMSPut. When you are finished with the array, you must close it with EMSClose. As many as 25 EMS arrays can be in use at one time, subject to limitations which may be imposed by your EMS driver (each array requires one EMS handle). EMSOpen Elements&, ElementType%, ArrayHandle%, ErrCode% Elements& number of elements in array (like DIM size) ElementType% numeric type of array (see above) ------- ArrayHandle% handle of an EMS array ErrCode% whether an error occurred (0 no) Name : EMSPut (EMS Put) Class : Memory Level : BIOS This routine puts an element into an EMS array created by EMSOpen. Element numbers start at 0. Be sure to use the right numeric type for the array-- for instance, if you opened the array for SINGLE precision, use "Value!". EMSPut ArrayHandle%, ElementNr&, Value ArrayHandle% handle of an EMS array ElementNr& element number to set Value value to set element to (must be correct type for array) Name : EMSRest (EMS Restore state) Class : Memory Level : BIOS This routine allows you to restore the state of the EMS array handler. Used in conjunction with EMSBuffer and EMSSave, it allows you to preserve EMS arrays across a CHAIN to another part of your program. EMSRest EMSState$ EMSState$ saved EMS array state Name : EMSSave (EMS Save state) Class : Memory Level : BIOS This routine allows you to save the state of the EMS array handler. Used in conjunction with EMSBuffer and EMSRest, it allows you to preserve EMS arrays across a CHAIN to another part of your program. EMSBuffer Bytes% EMSState$ = SPACE$(Bytes%) EMSSave EMSState$ ------- EMSState$ saved EMS array state Name : EnhKbd (Enhanced Keyboard) Class : Input Level : BIOS By default, the PBClone routines assume an old-style keyboard is in use, for greatest compatibility. EnhKbd allows you to turn on enhanced keyboard handling for the current generation of (usually) 101-key keyboards. This allows access to the F11 and F12 function keys as well as codes for key combinations that used to be ignored, among other things. The KbdType or KbdType2% routine can be used to determine if an enhanced keyboard is available (recommended). Note that EnhKbd works by intercepting the BIOS keyboard handler. All calls to the BIOS keyboard interrupt are converted from the old keyboard functions to the new ones. YOU MUST DISABLE EnhKbd BEFORE YOUR PROGRAM ENDS, so it can restore the old setup. Otherwise, the computer will most probably crash. A list of the new key codes is given in PBClone.DOC. EnhKbd Enable% Enable% turn on enhanced keyboard support (0 disable, else enable) Name : EuropeDate (European Date format) Class : Time Level : Any This routine takes a date in one of the American formats ("MM/DD/YY" or "MM-DD-YYYY") and converts it to the European convention ("DD.MM.YY" or "DD.MM.YYYY"). The date is formatted according to a format string which provides the desired delimiter and year length, e.g. "##-##-##" specifies a delimiter of "-" and a year length of two digits. An error code is returned if the date is not valid. EuropeDate DateSt$, Format$, Result$, ErrCode% DateSt$ date to format (month, day, year order) Format$ format for the date ------- Result$ resulting date (day, month, year order) ErrCode whether the date is valid (0 ok) Name : Equipment (Equipment information) Class : Equipment Level : BIOS This routine gives you some information about the basic equipment in your computer. Note that the "game port" information is not reliable, due to changes in the meaning of this particular area of the BIOS over many years. Equipment Memory%, Parallel%, Serial%, Game% ------- Memory% kilobytes of conventional memory installed (16 - 640) Parallel% parallel (printer) ports installed (0-4) Serial% serial (communications) ports installed (0-4) Game% game (joystick) ports installed (0-1). See remarks, above. Name : EWindowManagerC (EGA Window Manager with Character coordinates) Class : Display Level : Clone EWindowManagerC displays a pop-up window according to your specifications. The window may have any of a variety of frames, a title, or a shadow, and it may appear instantly or "grow" onto the screen. EGA and VGA graphics modes (SCREEN 7 through SCREEN 12) are supported. These are the available frame types: 0 no frame 1 single lines 2 double lines 3 single horizontal, double vertical lines 4 double horizontal, single vertical lines 5 block graphic lines These are the available shadows: 0 no shadow 1+ shadow attribute (use CalcAttr) for a colored shadow Options for growing windows are as follows: -1 grow as fast as possible 0 pop onto the screen 1+ grow with a specified delay in milliseconds (not recommended) The differences between this routine and its ProBas equivalent are the same as mentioned in the description for WindowManager. In addition, growing windows are supported, but are not recommended (too slow). Colored shadows work as in WindowManager. "True" shadows are not yet supported. EWindowManagerC TopRow%, LeftCol%, BottomRow%, RightCol%, Frame%, Fore%, Back%, Grow%, Shade%, S1%, S2%, TFore%, Title$ TopRow% top row of window LeftCol% left column of window BottomRow% bottom row of window RightCol% right column of window Frame% frame type (see above) Fore% frame foreground color Back% frame background color Grow% window growing option (see above) Shade% window shadow option (see above) S1% unused S2% unused TFore% title foreground color Title$ window title ("" if none) Name : Exist (file Existence) Class : Disk Level : DOS Most versions of BASIC give you no way of seeing if a file exists before you try to OPEN it, so you end up taking your chances. The Exist routine allows you to test to see if the file exists beforehand. It isn't really necessary for the PBClone file routines, which will return an appropriate error code, but it's an important safeguard when using the BASIC OPEN statement. The Exist routine does not support wildcards. If you need that feature, try the FindFirstFx and FindNextFx routines instead. See also Exist2, the FUNCTION version of this routine. Exist FileName$, Found% FileName$ name of the file to look for ------- Found% whether the file was found (0 if no) Name : Exist2% (file Existence) Class : Disk Level : DOS Most versions of BASIC give you no way of seeing if a file exists before you try to OPEN it, so you end up taking your chances. The Exist2% function allows you to test to see if the file exists beforehand. It isn't really necessary for the PBClone file routines, which will return an appropriate error code, but it's an important safeguard when using the OPEN statement. The Exist2% routine does not support wildcards. If you need that feature, try the FindFirstFx and FindNextFx routines instead. See also Exist, the SUB version of this routine. Found% = Exist2%(FileName$) FileName$ name of the file to look for ------- Found% whether the file was found (0 if no) Name : EXQPrintC (EGA Extended Quick Print, Character coords) Class : Display Level : Clone This routine provides a rather crude, but very fast, display capability. It works like the PRINT statement in BASIC, except that it doesn't move the cursor or process control codes. It works in EGA and VGA graphics modes (SCREEN 7 through SCREEN 12). EXQPrintC St$, Row%, Column%, Fore%, Back% St$ string to display Row% starting row Column% starting column Fore% foreground color Back% background color Name : ExtendFSpec (Extend File Specification) Class : Disk Level : DOS The ExtendFSpec routine combines a number of handy services together. It is intended for processing user-entered file specifications. It does the following: 1) Makes sure the filespec is valid 2) Formats the filespec to normal DOS standards 3) Tells you whether the drive and subdirectories specified exist 4) Fills out any drive or subdirectory information that was left out (optionally includes adding an extension to files which lack one) The error codes returned are as follows: -1 Invalid file specification 0 No error 1 Specified drive does not exist (warning only) 2 Specified subdirectory does not exist (warning only) The ExtendFSpec routine mimics DOS filename handling exactly, to the best of my knowledge. ExtendFSpec File$, Ext$, FullFile$, ErrCode% File$ file specification to process Ext$ extension to add to files that don't have extensions ------- FullFile$ processed file specification ErrCode% error code Name : ExtGet (Extended memory Get) Class : Memory Level : BIOS (AT) This routine allows you to get information from extended memory. It should only be used on AT-class computers, since older PCs do not support extended memory. You may get up to 32,766 words (just under 64 kilobytes) at a time from a specified location in extended memory. The location is specified as the distance from the start of extended memory, starting at 1 for the first location. One word is equivalent to one integer. See ExtMem for information on extended memory constraints. ExtGet DSeg%, DOfs%, Posn&, Words%, ErrCode% DSeg% segment of array in which to place data from extended memory DOfs% offset of array in which to place data from extended memory Posn& location of data in extended memory (starting at 1) Words% number of words to transfer (1 integer = 1 word = 2 bytes) ------- ErrCode% error code (0 if no error) Name : ExtMem (Extended Memory) Class : Memory / Equipment Level : BIOS (AT) This routine allows you to find out how much extended memory is available. It should only be used on AT-class computers, since older PCs do not support extended memory. The amount of memory returned may be either the total amount of extended memory installed or just the amount available at this time, depending on how previously-installed programs (if any) make use of extended memory. Unfortunately, there is no standard which defines how a program should use extended memory as there is with EMS (expanded memory), so there is no way for a program to determine whether or how another program is using extended memory. Microsoft is trying to clear up this situation with its HIMEM driver (available at your local BBS, or [last I looked] free from Microsoft), but this approach hasn't really become standard yet. ExtMem KBytes% ------- KBytes% the number of kilobytes of extended memory Name : ExtPut (Extended memory Put) Class : Memory Level : BIOS (AT) This routine allows you to put information into extended memory. It should only be used on AT-class computers, since older PCs do not support extended memory. You may put up to 32,766 words (just under 64 kilobytes) at a time into a specified location in extended memory. The location is specified as the distance from the start of extended memory, starting at 1 for the first location. One word is equivalent to one integer. Note that you can't rely on extended memory being available just because it exists. There is no automatic way to determine if another program is also trying to use the same extended memory. If in doubt, allow a user-installed option to enable/disable the use of extended memory by your program. ExtPut DSeg%, DOfs%, Posn&, Words%, ErrCode% DSeg% segment of data to store in extended memory DOfs% offset of data to store in extended memory Posn& location to place data in extended memory (starting at 1) Words% number of words to transfer (1 integer = 1 word = 2 bytes) ------- ErrCode% error code (0 if no error) Name : Extract (Extract delimited substring) Class : String Level : Any Extract allows you to remove any one of a list of delimited substrings in a string. It's useful for input parsing and database work. You pass it the string, delimiter, and the number of the desired substring (numbers start at one). It returns the starting position of the substring within the string and the length of the substring (0 if not found). Just for example, let's assume we have a string as follows: St$ = "Thomas G. Hanlin III=3544 E. Southern Ave #104=Mesa, AZ 85204" If we selected a delimiter of "=" and substring number three, the results would be "Mesa, AZ 85204". Delimiters of more than one character are fine. This can be handy for locating carriage return/linefeed pairs, among other things. Extract St$, Delimiter$, SubStrNr%, StartPosn%, SLen% SubSt$ = MID$(St$, StartPosn%, SLen%) St$ string from which to extract Delimiter$ delimiter between substrings SubStrNr% number of the desired substring ------- StartPosn% starting position of the substring within the string SLen% length of the substring (0 if none) Name : FadeOut (Fade Out) Class : Display Level : Clone Like CLS, but a bit more fancy, this routine provides an interesting way to clear the screen. See also Dissolve. FadeOut Attr% Attr% color/attribute to which to clear (see CalcAttr) Name : FarPeek% (Far memory Peek) Class : Memory Level : Clone This is like the BASIC PEEK function, but expects both a segment and an offset, thus doing away with the need for DEF SEG. This is especially handy for use in subprograms which might otherwise inadvertently change the DEF SEG value expected by the main program. Value% = FarPeek%(DSeg%, DOfs%) DSeg% segment of the location to look at DOfs% offset of the location to look at ------- Value% value at the specified memory location (byte: 0-255) Name : FarPoke (Far memory Poke) Class : Memory Level : Clone This is like the BASIC POKE statement, but expects both a segment and an offset, thus doing away with the need for DEF SEG. This is especially handy for use in subprograms which might otherwise inadvertently change the DEF SEG value expected by the main program. FarPoke DSeg%, DOfs%, Value% DSeg% segment of the location to look at DOfs% offset of the location to look at Value% value to store in the specified memory location (byte: 0-255) Name : FClose (File Close) Class : Disk Level : DOS This routine closes a file that was opened by FOpen or FCreate. It can also be used to close any of the predefined device handles. These are the predefined device handles that are always available: 0 CON stdin standard input, normally the keyboard 1 CON stdout standard output, normally the display 2 CON stderr standard error, almost always the display 3 AUX stdaux auxiliary device, generally COM1 4 PRN stdprn standard printer, generally LPT1 If you are running short of handles, you can always close stdaux to free up a handle. The stdprn device can also be closed as long as you don't use the printer or if you only access the printer through LPRINT. It is not a good idea to close stdin, stdout, or stderr under normal circumstances. FClose Handle% Handle% handle of the file to close Name : FCreate (File Create) Class : Disk Level : DOS This routine creates a file and opens it for use by the PBClone file handling routines. If the file already existed, it will be wiped out, so you may want to check beforehand if this is a problem. Try the Exist routine. The file is opened in read/write mode, allowing both input and output. You may create the file using any of the following attributes: Normal 0 (nothing special) Read Only 1 file can be read, but not written to Hidden 2 file is "invisible" System 4 special DOS system file The attributes can be combined by adding them together. Don't use the System attribute unless you know what you're doing! Note that this routine does not support file sharing. If that is a problem, close the file just after it is created and reopen it using FOpen. FCreate FileName$, Attr%, Handle%, ErrCode% FileName$ name of the file to create Attr% attribute(s) of the file ------- Handle% handle by which to access the file (if there was no error) ErrCode% error code: 0 if no error, else DOS Error Name : FGetLoc (File Get Location) Class : Disk Level : DOS This routine tells you the position of the file pointer of a file that was opened using FOpen or FCreate. This pointer is used to specify where the next item should be read from or written to the file. The first location of the file is numbered 1. See also FGetLoc2, the FUNCTION version of this routine. FGetLoc Handle%, Posn& Handle% handle of the file ------- Posn& location of the file pointer Name : FGetLoc2& (File Get Location) Class : Disk Level : DOS This routine tells you the position of the file pointer of a file that was opened using FOpen or FCreate. This pointer is used to specify where the next item should be read from or written to the file. The first location of the file is numbered 1. See also FGetLoc, the SUB version of this routine. Posn& = FGetLoc2&(Handle%) Handle% handle of the file ------- Posn& location of the file pointer Name : FileCopy (File Copy) Class : Disk Level : DOS This routine copies one or more files, just like the DOS command "COPY". FileCopy works exactly like the DOS COPY command, except it won't append files. You may use wildcards in both source and destination file specifications. In the event of an error, normal DOS error codes are returned, with two exceptions: -2 attempt to copy files over themselves -1 attempt to copy multiple source files to a single destination file See also CopyFile, a simpler routine which doesn't support wildcards. FileCopy SrcFile$, DestFile$, FileCount%, ByteCount&, ErrCode% SrcFile$ source file name(s) DestFile$ destination file name(s) ------- FileCount% number of files copied ByteCount& number of bytes copied ErrCode% error code (0 if no error) Name : FileCRC (File CRC) Class : Disk Level : DOS This routine calculates a 32-bit CRC for a file. This CRC is derived by a formula which takes each character of the file into consideration. It provides a powerful (although not 100% foolproof) way to verify that a file hasn't changed since you last checked. FileCRC FileName$, Result&, ErrCode% FileName$ source file name(s) ------- Result& 32-bit CRC of the file ErrCode% error code (0 if no error) Name : FindFirstA (Find First file in an Archive) Class : Disk Level : DOS The FindFirstA routine is used to find the first file that matches search parameters which you specify. Various information about the file that matches (if any) can be retrieved by other routines. Rather than working on a directory, this routine works on files in an archive. Supported archives include ARC, ARJ, LZH, PAK, ZIP and ZOO formats. If no extension is given, a search will be made through each valid archive extension, and the first matching archive will be used for the file search. Archive names may contain drive and subdirectory specifications, but not wildcards. File names may contain wildcards, but not drive/subdir specs. When you are done searching, be sure to use CloseA to terminate the search. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA FindFirstA ArcName$, FileName$, ErrCode% ArcName$ name of archive to search through FileName$ name of file(s) for which to search ------- ErrCode% error code (0 if no error, else no matching files) Name : FindFirstF (Find First File) Class : Disk Level : DOS This is part of a set of routines included for compatibility with ADVBAS and ProBas. A better solution may be found in FindFirstFx. The FindFirstF routine is used to find the first file that matches search parameters which you specify. Various information about the file that matches (if any) can be retrieved by other routines. See also FindNextF. The file name specified may contain a drive and subdirectory specification. Wildcards are also allowed. Possible search attributes are as follows: Normal 0 (nothing special) Hidden 2 file is "invisible" System 4 special DOS system file Subdirectory 16 subdirectory You can combine the attributes by adding them together. All searches will match if any of the specified attributes are found, so if you're looking only for a specific attribute, you will need to test the results using GetAttrF. Routines in this series include: FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL FindFirstF FileName$, Attr%, ErrCode% FileName$ name of file(s) for which to search Attr% file attribute(s) to seek ------- ErrCode% error code (0 if no error, else no matching files) Name : FindFirstFx (Find First File, Extended) Class : Disk Level : DOS The FindFirstFx routine is used to find the first file that matches search parameters which you specify. Various information about the file that matches (if any) can be retrieved by other routines. The file name specified may contain a drive and subdirectory specification. Wildcards are also allowed. Possible search attributes are as follows: Normal 0 (nothing special) Read Only 1 file can be read, but not written to Hidden 2 file is "invisible" System 4 special DOS system file Subdirectory 16 subdirectory You can combine the attributes by adding them together. All searches will match if any of the specified attributes are found, so if you're looking only for a specific attribute, you will need to test the results using GetAttrFx. Routines in this series include: FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$, GetSizeFx& These routines differ from the older FindFirstF-based series in two major respects. They include a Buffer$ parameter, which allows you to have more than one search going on at a time. This makes it safe to use these routines in subprograms without conflict with the main program. It also allows you to search entire subdirectory trees recursively. The other major difference is that many of these routines are coded as functions for greater convenience. Buffer$ = SPACE$(64) FindFirstFx Buffer$, FileName$, Attr%, ErrCode% FileName$ name of file(s) for which to search Attr% file attribute(s) to seek ------- Buffer$ buffer used in search (init to 64 characters) ErrCode% error code (0 if no error, else no matching files) Name : FindNextA (Find Next file in an Archive) Class : Disk Level : DOS This routine is for use after FindFirstA, to find any additional archived files which may match your search specifications. Routines in this series include: FindFirstA, FindNextA, GetNameA, GetCRCA, GetCRCAL, GetDateA, GetTimeA, GetSizeAL, GetStoreA FindNextA ErrCode% ------- ErrCode% error code (0 if no error, else no matching files) Name : FindNextF (Find Next File) Class : Disk Level : DOS This routine is for use after FindFirstF, to find any additional files which may match your search specifications. Routines in this series include: FindFirstF, FindNextF, GetNameF, GetAttrF, GetDateF, GetTimeF, GetSizeFL FindNextF ErrCode% ------- ErrCode% error code (0 if no error, else no matching files) Name : FindNextFx (Find Next File, Extended) Class : Disk Level : DOS This routine is for use after FindFirstFx, to find any additional files which may match your search specifications. Routines in this series include: FindFirstFx, FindNextFx, GetNameFx$, GetAttrFx%, GetDateFx$, GetTimeFx$, GetSizeFx& FindNextFx Buffer$, ErrCode% Buffer$ buffer used in search ------- Buffer$ updated buffer ErrCode% error code (0 if no error, else no matching files) Name : FindPatch (Find Patch location) Class : Disk Level : DOS This is one of a set of routines that allow you to write self-modifying code. Your program can patch DATA statements in itself or in another program, allowing you to save configuration information (for example) without having to create additional data files. In order for this routine to work, you must have a series of DATA statements containing quoted strings of the maximum desired length. The first DATA statement must contain a unique string, as FindPatch will use it to locate the data block. Note that if your program is patching itself, you must READ the unique string rather than assigning it directly, to make sure it's unique. The string must exist at only one place in the program. See the PDEMO.BAS file if you would like clarification. This little demo program, when compiled, will patch itself with whatever you enter on the command line. For instance, if you type PDEMO Banana, it will store "Banana" in its DATA statement. PDEMO will not work in the QuickBASIC environment, of course. You must compile it to an .EXE file. A precompiled version of PDEMO has been included. It was compiled with Crescent's PDQ library in addition to PBClone, which makes the .EXE file much smaller. It also doesn't capitalize COMMAND$. You can recompile PDEMO using the PCREATE.BAT program (PDQ is not required). You may compile the program using any switches. You may not use the /EXEPACK switch for LINK, though, as this may alter the program DATA area. Likewise, you must not use compression utilities such as PKLite on the program. Routines in this set include FindPatch, SetPatch, and PatchDone. FindPatch FileName$, SearchSt$, ErrCode% FileName$ name of the file to patch SearchSt$ value of the first DATA statement MoveBack% not used ------- ErrCode% whether the search was successful (0 yes, <0 no, >0 Disk Error) Name : Floppies (Floppies installed) Class : Equipment / Disk Level : BIOS The Floppies routine tells you how many floppy drives are installed (0-4). See also Floppies2, a function version of this routine. Floppies Drives% ------- Drives% number of floppy disk drives installed Name : Floppies2% (Floppies installed) Class : Equipment / Disk Level : BIOS The Floppies2 routine tells you how many floppy drives are installed (0-4). Drives% = Floppies2% ------- Drives% number of floppy disk drives installed Name : FloppyType (Floppy drive Type) Class : Equipment / Disk Level : Clone (AT) This routine tells you what kinds of floppy drives are installed, if any. A code is returned for each drive, 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. Note that this routine supports a maximum of only two drives. It is possible for a machine to have up to four drives, but there is not currently any good way to find out about them. FloppyType should only be used on AT-class machines. It will not work on PC/XT computers and may cause unusual results if used on such machines. It will also not work on some of the earliest AT machines, which didn't adhere to the standard CMOS format. FloppyType DriveA%, DriveB% ------- DriveA% drive type of first floppy drive DriveB% drive type of second floppy drive Name : FlushToDisk (Flush file buffers To Disk) Class : Disk Level : DOS This is a "file safety" routine for use with files opened by FOpen or FCreate. Files are normally buffered by DOS, which makes file handling faster but creates the danger of losing the file if there is a crash or power outage. By flushing the file to disk, you insure that it is updated to the current moment. Note: this routine will need to temporarily create a new file handle if DOS versions before 4.0 are used. FlushToDisk Handle%, ErrCode% Handle% handle of the file to flush ------- ErrCode% error code: 0 if none, else DOS Error Name : FOpen (File Open) Class : Disk Level : DOS This routine opens an existing file for use with the PBClone file handling routines. If you need to create a file that doesn't already exist, use the FCreate routine instead. The file may be opened for reading, writing, or both: 0 Read 1 Write 2 Read/Write You may specify a file sharing mode for use with networks and multitaskers. This will only take effect if the DOS version is 3.0 or later and if the DOS SHARE utility has been executed. Otherwise, it will be ignored. 0 Normal compatibility mode: no file sharing permitted 1 Exclusive no one else may access the file 2 Deny Write no one else may write to the file 3 Deny Read no one else may read from the file 4 Deny None anyone else may read from or write to the file Most of the time, "Deny Write" will be appropriate. This allows others to read the file, but not to modify the file on you unexpectedly. See the discussion of predefined device handles at FClose. FOpen FileName$, ReadWrite%, Sharing%, Handle%, ErrCode% FileName$ name of the file to open ReadWrite% whether to want to do input, output, or both (see above) Sharing% file sharing mode (see above) ------- Handle% handle by which to access the file (if there was no error) ErrCode% error code: 0 if no error, else DOS Error Name : ForceMatch$ (Force Match of file to wildcard) Class : Disk Level : Any The ForceMatch$ function allows you to mimic DOS commands that operate on source file(s) and destination file(s). It forces a source file name to match a specified pattern (which may contain wildcards), producing an appropriate destination file name. For example, if the source is "TESTNAME.BAS" and the pattern is "?RUE*.*", the result would be "TRUENAME.BAS". Consider the DOS command "COPY *.BAS A:*.BAK". The "*.BAK" part is the desired pattern. The "*.BAS" part specifies which files to copy to the new pattern. Each filename that matches "*.BAS" is translated through the "*.BAK" pattern to give the destination filename. The ForceMatch$ function is designed to do this sort of translation for you. DestFile$ = ForceMatch$(Pattern$, SrcFile$) Pattern$ pattern of desired file name (may contain wildcards) SrcFile$ file name to force through the pattern ------- DestFile$ resulting file name Name : FormatDate (Format Date) Class : Time Level : Any This is a highly flexible date formatting routine. It accepts a date in one of the usual American formats ("03-22-1990", "03/22/90", or even "3/22/90") and converts it according to a format string. This format string allows you to normalize the date, select a new delimiter, choose between two-digit and four-digit years, and even change the order from month/day/year to anything else. An error code will be returned if the date is not valid. The format string can be as simple as "##/##/##", which specifies that the usual month/day/year order be used, with a delimiter of "/" and a two-digit year. If you want to change the date order, you would need a format like "DD.MM.YYYY" instead. For sorting or storage, you might want to convert the date to a plain number, using a format string like "YYYYMMDD". The result could then be converted to a LONG with the BASIC VAL function. FormatDate DateSt$, Format$, Result$, ErrCode% DateSt$ date to format (month, day, year order) Format$ format for the date ------- Result$ resulting date ErrCode whether the date is valid (0 ok) Name : FSetEnd (File Set to End) Class : Disk Level : DOS This moves the file pointer to the end of the file. It is for use with files opened by FOpen or FCreate. The usual purpose for this is to append information to an existing file. Note that some text files may have a Control-Z or CHR$(26) on the end. For historical reasons, this character is sometimes used as an "end of file" marker. When dealing with text files, you may want to examine the last character of the file to make sure it isn't a Control-Z. QuickBASIC is among the programs which, unfortunately, put a Control-Z at the end of a file (if you OPEN for OUTPUT). This is a bad habit at best. FSetEnd Handle% Handle% handle of the file Name : FSetLoc (File Set Location to byte) Class : Disk Level : DOS This moves the file pointer to a specified position in the file. It is for use with files opened by FOpen or FCreate. File positions are considered to start at 1. FSetLoc Handle%, Posn& Handle% handle of the file Posn& location to which to move Name : FSetOfs (File Set location by Offset) Class : Disk Level : DOS This moves the file pointer backwards or forwards in the file. It is for use with files opened by FOpen or FCreate. FSetOfs Handle%, Offset& Handle% handle of the file Offset& number of bytes by which to move Name : FSetRec (File Set location to Record) Class : Disk Level : DOS This sets the file pointer to a specific record in the file. It is for use with files opened by FOpen or FCreate. This routine provides the same function as FSetLoc, but is a bit more convenient for dealing with files composed of fixed-length records. FSetRec Handle%, RecSize%, RecNr% Handle% handle of the file RecSize% number of bytes per record RecNr% number of record (starting at 1) Name : FSetSize (File Set Size) Class : Disk Level : DOS Many people have asked how to delete information from a file. Well, there's no straightforward way to do it most of the time, but if the record is at the end of the file, you can chop it right off. This routine can also be used to make a file larger, perhaps pre-allocating space that will be used later (for better speed). The file in question must have been opened by FCreate or FOpen. FSetSize Handle%, Bytes& Handle% handle of the file Bytes& desired file size, in bytes Name : FSize (File get Size) Class : Disk Level : DOS This routine allows you to get the size of a file that was opened by FOpen or FCreate. See also FSize2, the FUNCTION version of this routine. FSize Handle%, Bytes& Handle% handle of the file ------- Bytes& file size, in bytes Name : FSize2& (File get Size) Class : Disk Level : DOS This routine allows you to get the size of a file that was opened by FOpen or FCreate. See also FSize, the Sub version of this routine. Bytes& = FSize2&(Handle%) Handle% handle of the file ------- Bytes& file size, in bytes