Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / BASIC / BASDLX14.ZIP / BASDLX.DOC next >

Wrap

Text File | 1987-04-01 | 36.3 KB | 961 lines

BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 1 BASDLX.LIB Deluxe Library of functions written in assembly language for Compiled BASIC BASDLX, Basic Deluxe, is a library of handy functions for com- piled BASIC. To use BASDLX.LIB you will need, either the IBM Basic compiler or the Microsoft Quickbasic compiler. I suggest that you use PC-DOS/MS-DOS versions 2.0 or later to insure full compatibility. These functions have been tested with the IBM Basic compiler version 2.0 and have caused no problems. However, I am not responsible for any damages caused by but, not limited to, the use, misuse, non-use or inability to use BASDLX. These deluxe function are intended to be used in compiled basic only. Do not confuse compiled BASIC with the BASIC interpreter, BASIC.COM or BASICA.COM that comes with DOS or GWBASIC. The func- tions provided in this library have been designed to run faster than any correspondent BASIC code, and often take up less space, leaving you with more room to write longer programs! This is the fourth, of many public releases of the Basic Deluxe library. You are free to use the functions provided in the BASDLX library in your programs. The copyright is only here to preserve my work and to protect you from any unauthorized modifications of BASDLX; it is NOT here to protect against the free distribution of BASDLX. You may copy and distribute BASDLX to others as long as no fee or special consideration is charged and all of the re- lated files to BASDLX are included together in the unmodified form. If you use BASDLX in your programs and find it a valuable tool then I would appreciate it if you would send a contribution ($25 suggested). It would be nice if you could acknowledge use of BASDLX functions in your programs or documentation that use them. With a minimum contribution of $25 I will send you a disk with the source code to BASDLX. Previous contributors will need only send $10 for an update of BASDLX. A contribution of $55 will grant you a one year subscription to BASDLX. With a subscription you will automatically receive new updates as soon as they come out (about 10 updates per year.) Updates come complete with source code, BASDLX library, and documentation. These functions have been incorporated into a library to make them easily accessible by the DOS LINK.EXE program. All you have to do is copy BASDLX.LIB to the directory or disk where you keep your library files. When you link your programs that use func- tions from BASDLX, be sure to specify: BASDLX when the linker prompts you for a Library [.LIB] file(s). Please refer to your DOS manual for more information on the LINK.EXE program. --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 2 Special Notes The functions provided in this library are available to you by using the CALL command from compiled BASIC. All numeric variables passed as arguments to the functions must defined as integers. This means that you can either globally set all numeric variables to integers by issuing the DEFINT A-Z command at the beginning of your program or, you can declare a single variable as integer by adding a "%" symbol at the end of its name. (i.e. I%, this will declare the variable as being integer). I will always add the "%" symbol at the end of all my numeric variables in all of my ex- amples, to remind you that they MUST be integers. The variable names used in my examples don't have to be exactly the same. you may choose other names that would be more ap- propriate. keep in mind that the variable types do have to be the same in the argument list (i.e. strings must be strings, integers must be integers). NOTE: I have now updated the documentation to show which vari- ables can be entered directly in the argument list. for example, the following is an acceptable way to call the GUN function: CALL GUN(10) This will "fire" the gun 10 times and return. The only difference between the above example and s%=10: CALL GUN(S%) is that by inserting a number instead of a variable name BASIC as- signs that number to a local variable which is erased upon return from the function (i.e. variable space is preserved.) Not all functions in BASDLX can be CALLed in this way because they sometimes return with a special code in the variable. In the documentation any arguments enclosed in []'s can be entered directly as the argument. As I mentioned before I have tested these functions and they, to the best of my knowledge, work bug free. But, if you happen to find any bugs I'll be happy to fix them. Be sure to check that you are CALLing the functions properly. That is that you are sending the correct arguments to the function. One of the most common error that occurs is when the calling program sends to the function an incorrect variable type. Remember that numeric variables must be declared integer. Please refer any questions, comments, requests for new functions or contributions to the following address: Gustavo H. Verdun 6424 Hollins Drive Bethesda, MD 20817 --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 3 Function Name: ALLDRIVES Arguments : (Num_of_drives) Type : DOS/System Purpose : Returns the total number of logical drives (Diskette, Fixed, Ram, Etc.) Available. Description : This function will return a minimum of 2 Drives, since any com- puter is assumed to have the logical drives A: & B: Even if there is only one physical drive. drvs%=0:call alldrives(drvs%) print "You have ";drvs%;" drives available." Function Name: ALLDIRS Arguments : (Dir.Array$(),Maxdirs%,Drive$,Ercd%) Type : DOS/System Purpose : Searches and returns all of the directories in Drive$. Description : Dir.Array$(0), This is where the directory names found will be saved. Each element in this ONE dimensional array must be set to some length. ALLDIRS is not very picky about the minimum length but if it ever finds a directory path that will not fit in the space provided it will stop and return with an `out of string space condition'. DOS limits the maximum length of any directory path to 64 characters including the drive specifier (i.e. C:), slashes and end marker (ASCII 0) So, you will never need more than a string length of 64 characters per element. Maxdirs%, tells ALLDIRS the number of elements in Dir.Array$(). If ALLDIRS finds more directories than space is provided then ALLDIRS stops and returns with a `Out of string space condition'. Upon return from ALLDIRS, Maxdirs%= the number of directories found. Drive$, Specify drive to search. The first character in this string must specify the drive letter all other characters, if any, are ignored. (ALLDIRS will NOT convert the drive letter to upper case, you may have to do it separately if it is important.) Ercd%, like all disk functions, errors may occur. If, Ercd%=0 then everything is o.k. An error code of -1 = Drive selected is not valid. -2 = Out of String space. --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 4 Function Name: ALLDIRS (continued) Example: Dim dir.array$(50):for i=0 to 50:dir$(i)=space$(64):next:d$="C:" ercd%=0:max%=51:call alldirs(dir.array$(0),max%,d$,ercd%) if ercd% then print "Error :";ercd% print "Directories found:" for i= 0 to max%:print dir$(i):next Function Name: BSORTN Arguments : (Num_of_elements,Integer_array%(start)) Type : integer array service Purpose : Sorts an integer array in ascending order with negative numbers appearing at the end in ascending order. Description: Integer variables in BASIC can contain numbers between -32,768 and 32,767. This function does not distinguish between negative or positive numbers. It will sort the elements in ascending order with all the negative numbers (if existing) appearing after the positive numbers in ascending order. Make sure that the array is of type integer. Unpredictable results may occur if not! Example: dim a%(300):print "Array Before sort:" for i%=0 to 300:a%(i%)=int(rnd(1)*30000):print a%(i%),:next enum%=301:call bsortn(enum%,a%(0)) rem enum%=301 because there are 301 elements in the array (0-300) print "Array After sort:":for i%=0 to 300:print a%(i%),:next rem the list should be sorted in ascending numerical order! --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 5 Function Name: BSORTS Arguments : (Num_of_elements%,Array$(start_position)) Type : String array service Purpose : Sorts a string array in ascending alphabetical order. Description: The first argument should contain the number of elements to sort in the array. The second argument is the array itself. be sure to specify the starting position in the array [i.e. BSORTS(elements%,a$(0))] IMPORTANT: All of the elements in the array MUST have equal lengths, if not, unpredictable results will occur to BASIC Example: dim a$(10):a$(0)"First":a$(1)="Second":a$(2)="Third" a$(3)="Fourth":a$(4)="Fifth":a$(5)="Sixth":a$(6)="Seventh" a$(7)="Eighth":a$(8)="Ninth":a$(9)="Tenth" for i%=0 to 9:b$=space$(10):call setl(a$(i%),b$):a$(i%)=b$:next rem the above line will make all of the elements in the array rem have equal lengths. print "Array before sort:":for i%=0 to 9:print a$(i%):next enum%=10:call bsorts(enum%,a$(0)) rem enum%=10 because there are 10 elements in the array (0-9) print "Array After sort:":for i%=0 to 9:print a$(i%):next rem the list should be sorted in ascending alphabetical order! Function Name: CNFGSD Arguments : ([overwrite%],[insert%],[frame%],[tab%]) Type : Configuration for GETSTRD Purpose : Change default settings for GETSTRD. Description : [Overwrite%] & [Insert%], (Default is Full & Half size cursor respectively) These two arguments contain the cursor shapes that indicate if overwrite or insert is active. The formula for the values that must be stored in these two arguments is as follows: =(START and 31)*256+STOP Where START & STOP are the values for cursor start & stop scan lines which must be in the range of 0- 31. (See the BASIC LOCATE command for more information on cursor shapes.) NOTE: a value of zero for these options leaves their current defaults in effect. [Frame%], (Default ASCII 95) This argument contains the ASCII code for the frame character. GETSTRD draws a one line frame of the length of String$ to let you see the field size. A value of zero for this option leaves its current default in effect. --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 6 Function Name: CNFGSD (Continued) [Tab%], (Default 1) Number of spaces to insert for a [TAB] key. Valid number is in the range of 0-10. A value above 10 leaves the current default unchanged. Example: oc%=(0 and 31)*256+7:ic%=(5 and 31)*256+7 'rem this is here to 'rem show the values of the default cursors. ic%=0:oc%=:frame%=177:tab%=0:call cnfgsd(ic%,oc%,frame%,tab%) -In this example: Insert & overwrite cursor values are unchanged. Frame character is set to ASCII 177. [TAB] key will insert 0 spaces in string (disables [TAB] key). NOTE: If ASCII 32 (space) is not a valid key in GETSTRD then [TAB] does nothing. Function Name: DATESTR Arguments : (String_space$,Length%,mode%) Type : Date support Purpose : Reads the date and writes string_space$ with the date in the following format: week-day month day, year. (i.e. Thursday, March 12, 1987) Description : The first argument, String_space$, must be of at least 30 characters of length. If Length% returns with a zero then there wasn't enough space in the string variable String_space$. The Mode% argument tells the function to either write the full name of the week-day and month or just the first three letters of each. If Mode%=0, or any number other than one, then the full names of the week-day and month will be written. If Mode%=1 then only the first three characters of the week-day and month will be written. The Length% argument is used to tell BASIC the true and final length of String_space$ (This way you easily get rid of the trailing characters after the year since, the actual length of String_space$ will vary greatly depending on the date.) NOTE: String_space$ will never be any longer than 30 characters of length. Example: D$=space$(30):l%=0:mode%=0:call datestr(d$,l%,mode%) if l%=0 then print "Not enough space in D$!":stop d$=left(d$,l%):print "Today is ";d$ D$=space$(30):l%=0:mode%=1:call datestr(d$,l%,mode%) if l%=0 then print "Not enough space in D$!":stop d$=left(d$,l%):print "Today is ";d$ --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 7 Function Name: GETSTRD (Improved in this Version) Arguments : (String$,length%,Validkeys$,[color%],mode%) Type : String/Data entry enhancement Purpose : This function accepts input from the keyboard and stores it in the String$ argument allowing the use of standard editing commands. Description : To start with I will describe each of the arguments: String$, This is the space where the input data will be stored. The field size of the input data will be set to the length of this string. If there is already some data in the string it will not be erased. Just be sure to set the length to the proper value to let GETSTRD know that there is already data in the String$ variable that is ready to be edited. Due to the limitations that BASIC imposes on assembly language with variables, the String$ variable must be filled in to the maximum size of the field. Length%, If you have a string length that is shorter than the field size that you have allocated for the data, GETSTRD will be able to know and upon return tell you the actual length of the string. This makes it easy to remove the trailing spaces in the String$ if they are not important. A Length% of zero tells GETSTRD that it is a `fresh' data field containing no previous input. Validkeys$, This is the new option added to GETSTRD. If this string is set to null (i.e. length of 0) then GETSTRD will accept all keys from ASCII 32-126, otherwise GETSTRD will accept only the keys defined in this string. (Control keys, except ^M [Return], ^[ [Escape], ^H [Backspace], & ^I [Tab], are always discarded.) [Color%], here, you may specify the color attribute that GETSTRD will use. The formula for the color value is as follows: Color%=(BACKGROUND and 7)*16+FOREGROUND Mode%, GETSTRD currently supports two modes of operation. If Mode%=0 GETSTRD will operate normally without exiting unless [ESC] or [RETURN] is pressed. If Mode%=1 GETSTRD will operate normally except that if it reads from the keyboard an extended scan code that is not one of it's editing commands it will exit the function and return with the extended scan code to that key in Mode%. This feature makes it easy to write programs that allow the user to scroll through other data fields without changing or having to re-enter data. If upon exit from the GETSTRD function Mode%=-1 then the [ESC] key was pressed and your program should do whatever the [ESC] key means. If [ESC] means nothing to your --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 8 Function Name: GETSTRD (Continued) program then just go back to the line that CALLs GETSTRD and con- tinue. The following Editing keys are supported: [LEFT-ARROW] Move cursor one space left. [RIGHT-ARROW] Move cursor one space right. [HOME] Move cursor to beginning of line. [END] Move cursor to the end of line. (NOTE: The end of the line is determined by the current length of the input data and not the maximum length of the data field.) [CTRL]-[RIGHT-ARROW] Move cursor one word right. [CTRL]-[LEFT-ARROW] Move cursor one word left. [CTRL]-[HOME] Erase entire input field. [CTRL]-[END] Erase from cursor position to the end of the line. [INS] Set/Clear Insert mode. [DEL] Deletes character at cursor position. [BACKSPACE] Deletes character to the left of cursor. [TAB] Inserts x spaces. (See function CNFGSD) Example : 10 rem This example is for mode 0. 12 mode%=0 14 c%=31:A$="":valkey$="0123456789()-" ' Valid keys for phone #. 18 l%=len(A$):b$=space$(15):call setl(a$,b$):a$=b$ 'rem add field 20 print "Enter Phone #"; 22 call getstrd(a$,l%,valkey$,c%,mode%) 24 a$=left$(a$,l%):if mode%=-1 then 18 . 10 rem this example is for mode 1. 12 mode%=1:c%=31:A$="" 18 l%=len(A$):b$=space$(25):call setl(a$,b$):a$=b$:rem add field 20 locate 10,5:print "Enter Name : ";:valkey$="" 22 call getstrd(a$,l%,valkey$,c%,mode%) 24 a$=left$(a$,l%):if mode%=-1 then 36 26 l%=len(C$):b$=space$(15):call setl(C$,b$):C$=b$:rem add field 28 locate 11,5:print "Enter Phone # ";:valkey$="01234567890()-" 30 call getstrd(c$,l%,valkey$,c%,mode%) 32 a$=left$(c$,l%):if mode%=-1 then 36 34 if mode%=72 or mode%=80 then 18 36 print "Data A: ";a$:print "Data B: ";c$:end --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 9 Function Name: GUN Arguments : ([Num_of_shots%]) Type : Speaker support Purpose : Simulates the sound of a gun or machine gun Description : This function generates the sound by sending spurts of white noise to the speaker. This will create the sound of a quick ex- plosion. the only parameter needed is the number of shots to fire. Example: input "Number of shots to fire :",shots%:if shots%=0 then end call gun(shots%) Function Name: READP Arguments : (Port_num%) Type : Printer support Purpose : Reads the printer status of the specified port number (1-3) and returns with the status byte for that port in the Port_num% variable. Description: The status byte of contains the following information: bit: 7 6 5 4 3 2-1 0 | | | | | | |_Time out | | | | | |_Unused | | | | |_1 = I/O Error | | | |_1 = Selected | | |_1 = Out of Paper | |_1 = Acknowledge |_1 = Not Busy IMPORTANT: This function does not check for a valid port number. Be sure that the port number is in the range of 1-3 Example: port%=1:call readp(port%):print port% if port% and 32=32 then print "Printer is out of paper" if port% and 128=0 then print "Printer is Off-line" --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 10 Function Name: RESETP Arguments : (Port_num%) Type : Printer support Purpose : Resets the specified printer port number (1-3) and returns with its status byte (see the READP function description for information on the printer status byte) Description: This function sends a reset status through the parallel inter- face of the specified port number. This function does check the parameters to be sure that they are in the range of 1 to 3. If the Port_num% argument is equal to -1 upon return then the port number is not valid. Example: port%=1:call resetp(port%):print port% if port%=-1 then print"Port number must be in the range of 1-3" if port% and 32=32 then print "Printer is out of paper" if port% and 128=0 then print "Printer is Off-line" Function Name: SETL Arguments : (Source_string$,Destination_string$) Type : String manipulation Purpose : This function will place the source string inside of the destination left-justified. If the source string is longer than the destination string then the right portion of the string will be truncated. Description : This function automatically clears the destination string to spaces (ASCII 32) even if the source string is of length zero. Be sure to save the destination string into the source string after the call. Example: a$="Enter Name":b$=space(20):call setl(a$,b$):a$=b$ rem the last command "a$=b$" saves the destination string in the rem source string since the function cant' change the length of rem any string. print ">";a$";"<":REM this will show you the new length of a$ --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 11 Function Name: SETR Arguments : (Source_string$,Destination_string$) Type : String manipulation Purpose : This function will place the source string inside the destination string right justified. If the destination string is shorter than the source string then the right portion of the string will be truncated. Description : This function automatically sets the destination string to all spaces (ASCII 32) even if the source string is of length zero. Be sure to save the destination string into the source string after the call. Example: a$="Enter Name":b$=space(20):call setr(a$,b$):a$=b$ rem the last command "a$=b$" saves the destination string in the rem source string since the function cant' change the length of rem any string. print ">";a$;"<":REM this will show you the new length of a$ Function Name: SNDOFF Arguments : NONE Type : Speaker support Purpose : Turns speaker off. If this function is used then the BASIC SOUND or BEEP commands will not work. Description : This function can be useful for those programs that use sound prompts to get attention when input is required. With this func- tion you can easily add the feature to your programs that will let the user decide if he wants to have the sound prompts on or off. If he wants the off then at the beginning of your program just call this function. Any sound statements following this com- mand will execute without producing a single sound. Be sure not to forget to turn them on before the program finishes (SNDON). Example : sound 200,1:sound 300,1:sound 400,1:call sndoff sound 200,1:sound 300,1:sound 400,1 --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 12 Function Name: SNDON Arguments : NONE Type : Speaker support Purpose : Turns sound on so that the BASIC SOUND and BEEP commands work. Description: This function can help solve the problem that occurs when you use some memory resident programs that use the speaker and when they are done the turn it off so that any SOUND or BEEP commands won't produce an audible signal. It can also turn on the sound when it was turned off by the function SNDOFF! Example: sound 200,1:sound 300,1:sound 400,1:call sndoff sound 200,1:sound 300,1:sound 400,1:call sndon sound 200,1:sound 300,1:sound 400,1 Function Name: TIMESTR Arguments : (String_space$) Type : Time support Purpose : Reads clock and loads String_space$ with the time in decimal ASCII. The format is as follows: HH:MM:SS.HD Where, HH are hours,MM are minutes, SS are seconds and, HD are Hundredths of a second. Description : String_space$ must be of at least 11 characters of length for this function to work successfully. If it is not of the proper minimum length then the function will do nothing and return with the String_space$ unmodified. Example: t$=space$(11):call timestr(t$):print t$ Function Name: XLC Arguments : (String$) Type : String manipulation Purpose : Converts the string to lower case. Description: No further explanations are necessary, I hope! Example: a="THIS WILL BE IN LOWER CASE!":call xlc(a$):print a$ --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 13 Function Name: XUC Arguments : (String$) Type : String manipulation Purpose : Converts the string to upper case. Description: No further explanations are necessary, I hope! Example: a="this will be in upper case!":call xuc(a$):print a$ --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 14 Summary of functions Please use this as a quick summary to BASDLX functions. This sum- mary should only be used once you understand the functions, but just need a quick refreshment. Function Name: ALLDRIVES Arguments : (Num_of_drives) Type : DOS/System Purpose : Returns the total number of logical drives (Diskette, Fixed, Ram, Etc.) Available. Function Name: ALLDIRS Arguments : (Dir.Array$(),Maxdirs%,Drive$,Ercd%) Type : DOS/System Purpose : Searches and returns all of the directories in Drive$. Function Name: BSORTN Arguments : (Num_of_elements,Integer_array%(start)) type : integer variable service Purpose : Sorts an integer array in ascending order with negative numbers appearing at the end in ascend- ing order. Function Name: BSORTS Arguments : (Num_of_elements%,Array$(start_position)) Type : String service Purpose : Sorts a string array in ascending alphabetical order. Function Name: CNFGSD Arguments : ([overwrite%],[insert%],[frame%],[tab%]) Type : Configuration for GETSTRD Purpose : Change default settings for GETSTRD. Function Name: DATESTR Arguments : (String_space$,Length%,mode%) Type : Date support Purpose : Reads the date and writes string_space$ with the date in the following format: week-day month day, year. (i.e. Thursday, March 12, 1987) Function Name: GETSTRD (Improved in this Version) Arguments : (String$,length%,Validkeys$,[color%],mode%) Type : String/Data entry enhancement Purpose : This function accepts input from the keyboard and stores it in the String$ argument allowing the use of standard editing commands. --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 15 Summary of functions (Cont.) Function Name: GUN Arguments : (Num_of_shots%) Type : Speaker support Purpose : Simulates the sound of a gun or machine gun Function Name: READP Arguments : (Port_num%) Type : Printer support Purpose : Reads the printer status of the specified port number (1-3) and returns with the status byte for that port in the port_num% variable. Function Name: RESETP Arguments : (Port_num%) Type : Printer support Purpose : Resets the specified printer port number (1-3) and returns with its status byte (see the READP function description for information on the printer status byte) Function Name: SETL Arguments : (Source_string$,Destination_string$) Type : String manipulation Purpose : This function will place the source string inside of the destination left-justified. If the source string is longer than the destination string then the right portion of the string will be truncated. Function Name: SETR Arguments : (Source_string$,Destination_string$) Type : String manipulation Purpose : This function will place the source string inside the destination string right justified. If the destination string is shorter than the source string then the right portion of the string will be truncated. Function Name: SNDOFF Arguments : NONE Type : Speaker support Purpose : Turns speaker off. If this function is used then the BASIC SOUND or BEEP commands will not work. Function Name: SNDON Arguments : NONE Type : Speaker support Purpose : Turns sound on so that the BASIC SOUND and BEEP commands work. --- BASDLX Version 1.4 April 1987 --- BASDLX (C) Copyright 1986,1987 By Gustavo H. Verdun Page 16 Summary of functions (Cont.) Function Name: TIMESTR Arguments : (String_space$) Type : Time support Purpose : Reads clock and loads String_space$ with the time in decimal ASCII. The format is as follows: HH:MM:SS.HD Where, HH are hours,MM are minutes, SS are seconds and, HD are Hundredths of a second. Function Name: XLC Arguments : (String$) Type : String manipulation Purpose : Converts the string to lower case. Function Name: XUC Arguments : (String$) Type : String manipulation Purpose : Converts the string to upper case. --- BASDLX Version 1.4 April 1987 ---