Power-Programmierung

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

/ Power-Programmierung / CD1.mdf / basic / library / qb_pds / dos / qbdos / qbdos.doc < prev next >

Wrap

Text File | 1987-10-14 | 58.6 KB | 2,905 lines

Q B W A R E / 1 QBDOS.LIB THE QUICKBASIC DOS INTERFACE LIBRARY Version 1.0 R E F E R E N C E M A N U A L AJM Software P.O. Box 5303 Arvada, Co. 80005-0303 Copyright (c) 1987 AJM Software All Rights Reserved TABLE OF CONTENTS I. Introduction to QBDOS.LIB ........................... 2 II. A word about User supported software ................ 3 III. Warranty Information ................................ 5 IV. Registration and License Information ................ 6 V. Product Support ..................................... 10 VI. AJM Software Shareware Products ..................... 11 VII. Using QBDOS.LIB ..................................... 12 VIII. PRECAUTIONS (READ THIS SECTION) ..................... 14 IX. Miscellaneous DOS services .......................... 15 X. The Print Spooler ................................... 25 XI. DOS Memory Management ............................... 31 Copyright (c) 1987, AJM Software -Page 1- Introduction to QBDOS.LIB QBDOS.LIB is the part 2 of the 3-part QBWARE/1 package. The entire package also includes QBFILE.LIB and QBBIOS.LIB. The other packages will are described briefly in this documentation and are available immediately through AJM Software or should be available through normal shareware chan- nels before November 1, 1987. All of these products are sold together as QBWARE/1, but because of the wide functional differences between each library, the documentation and library routines are being kept separate. Any mention of QBWARE/1 in this documentation references all three libraries. QBDOS.LIB is a series of assembler language subroutines specifically designed to provide an easy to use interface between Quickbasic programs and certain DOS facilities that would normally be unavailable to a Quickbasic program. These include access to the DOS print spooler and memory management routines. It is very important to read the manual before using any of these services, as proper setup is important. Quickbasic is a registered trademark of Microsoft. Copyright (c) 1987, AJM Software -Page 2- A Word about User-supported Software User-supported software is a means for the computing community to receive quality software while directly supporting software authors. It is based on the ideas that: The value and utility of software is best assessed by the user on his or her own system. Only after using a program can one really determine whether it serves personal applications, needs and tastes. The creation of independent personal computer software can and should be supported by the computing community. Copying of programs should be encouraged, rather than restricted. The ease with which software can be distributed outside traditional commercial channels reflects the strength, rather than the weakness, of electronic information. Under the user supported concept, anyone may request a copy of a user-supported program by sending a blank, formatted disk to the program author together with an addressed, postage-paid return mailer. A copy of the program, along with documentation on disk, will be sent by return mail on the user's disk. The program carries a notice suggesting registration for the program. You should register if you are going to use the program on a regular basis. Regardless of whether you register and use the program, you are encouraged to copy and distribute the program for the private, non-commercial, trial use of others. User supported software is generally not public domain material; most programs of this nature carry a copyright notice. Rather, the author has licensed you to copy and use the program under certain conditions. Likewise, user supported software is not intended to be free software; it is an experiment in economics, not altruism. It is intended to provide quality software at a low price, while directly supporting the author, without the overhead of distributors, dealers and advertising that produces $500 software packages. User supported software is having a hard time. More and more packages are being taken out of this market, and offered as more traditional, and expensive, products. The reason for this is simple: lots of people are using the packages but very few are paying for them. And without the support of the users, there is absolutely no incentive for software authors to provide their programs in this fashion. Copyright (c) 1987, AJM Software -Page 3- There are many good reasons to register. Besides supporting the author (that is, paying for the software you use), you generally get better support and receive mailed notification of updates and other products. In conclusion, if you regularly use a user supported program (sometimes called Freeware or Shareware) and have not sent in a registration to the author, please do so now. Only through the financial support of users will this kind of inexpensive software continue to be available. Copyright (c) 1987, AJM Software -Page 4- WARRANTY AJM Software makes no warranty of any kind, express or implied, including without limitation, any warranties of merchantability and/or fitness for a particular purpose. AJM Software shall not be liable for any damages, whether direct, indirect, special or consequential arising from a failure of this program to operate in the manner desired by the user. AJM Software shall not be liable for any damage to data or property which may be caused directly or indirectly by use of the program. IN NO EVENT WILL AJM Software BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF YOUR USE OR INABILITY TO USE THE PROGRAM, OR FOR ANY CLAIM BY ANY OTHER PARTY. Copyright (c) 1987, AJM Software -Page 5- Registration and ordering information A QBWARE/1 registration licenses you to use the product on a regular basis. Registration includes mailed notification of updates and priority support. Users need register only one version of QBWARE/1 - registration includes licensed use of all upgrades. Individual registrations for QBWARE/1 are available from AJM Software at a cost of $39.00. AJM will provide you with the most current release of QBDOS.LIB in both object and assembly source code form on 5 1/4 inch diskette. The reference manual will also be included on the diskette. A bound reference manual is available for an additional $25.00. Registration entitles you to include any QBWARE/1 routine in your applications for distribution without royalty. Including QBWARE/1 in your applications without registration is strictly prohibited. Quantity discounts are available. Please see the section titled 'Corporate and quantity purchases'. In addition, evaluation disks are available at any time for $10. These disks do not include registration. The fee covers diskette, postage and handling. Please use the enclosed order form when placing an order. ORDERS OUTSIDE THE US: Please include an additional $10.00 to cover additional postage and handling costs. No C.O.D.'s will be accepted on orders delivered outside the US. Copyright (c) 1987, AJM Software -Page 6- Remit to: AJM Software Order Form P.O. Box 5303 Arvada, CO 80005-0303 Please send: ____ QBWARE/1 Disk (Evaluation only) ........... @ $ 10.00 ea $ ______ (includes QBBIOS,QBDOS,QBDOS routines and manual on disk) ____ QBWARE/1 Registration ..................... @ $ 39.00 ea $ ______ (includes QBWARE/1 disk and source code) ____ QBWARE/1 Bound Reference Manual ........... @ $ 25.00 ea $ ______ (includes only the reference manual) Subtotal ______ Less Discount <______> C.O.D. Fee ($5.00) ______ Total $ ______ Payment by: ( ) Check ( ) C.O.D. Name: ____________________________________________________________ Company: ____________________________________________________________ Address: ____________________________________________________________ : ____________________________________________________________ : ____________________________________________________________ Day Phone: _________________________ Eve: ___________________________ ORDERS OUTSIDE THE US: Please include an additional $10.00 to cover additional postage and handling costs. No C.O.D.'s will be accepted on orders delivered outside the US. Copyright (c) 1987, AJM Software -Page 7- Corporate and Quantity Purchases All corporate, business, government or other commercial users of QBDOS.LIB must be registered. We offer quantity discounts starting at the sixth copy. Orders in quantities of less than 50 units are handled as bulk purchases. Purchases of over 50 units may be handled as quantity purchases or as corporate licensing agreements. Licensing agreements allow duplication and distribution of specific numbers of copies within the licensed institution. Duplication of multiple copies is not allowed except through execution of a licensing agreement. Please write for details. The quantity purchase discounts are as follows: 0- 5 copies: no discount 6- 20 copies: 20% discount 21+ copies: 40% discount ALL PRICES AND DISCOUNTS ARE SUBJECT TO CHANGE WITHOUT NOTICE. Discounts are not cumulative; they apply to single orders of like products only. Unit prices are the same as for individual users. WARNING: YOU MAY NOT USE QBWARE/1 WITHIN YOUR ORGANIZATION WITHOUT A PRIOR PURCHASE OR LICENSE ARRANGEMENT. Copyright (c) 1987, AJM Software -Page 8- LICENSE All versions of QBWARE/1, including version 1.0, are not public domain software, nor are they free software. QBWARE/1 is copyright (C) 1987 by AJM Software Non-registered users are granted a limited license to use QBWARE/1 on a trial basis for the purpose of determining whether it is suitable for their needs. Use of QBWARE/1, except for this limited purpose, requires registration. Use of non-registered copies of QBWARE/1 by any person, business, corporation, governmental agency or other entity institution is strictly forbidden. Registration permits a user the license to use QBWARE/1 for development purposes, only on a single computer. QBWARE/1 can be included into any program and distributed in library form only without royalty. A registered user may use the program on a different computer, but may not use the program on more than one computer at the same time. All users are granted a limited license to copy QBWARE/1 only for the trial use of others subject to the above limitations, and also the following: QBWARE/1 must be copied in unmodified form, complete with the file containing this license information. The full QBWARE/1 documentation must be included with the copy. No fee, charge or other compensation may be accepted or requested by any licensee, except a handling fee not to exceed $10.00 QBWARE/1 may not be distributed in conjunction with any other product. The ASSEMBLY source code for QBWARE/1 may NOT be distributed under any circumstances. The object modules supplied with a registered copy of QBWARE/1 may NOT be distributed under any circumstances. Operators of electronic bulletin board systems (Sysops) may post QBWARE/1 for downloading by their users only as long as the above conditions are met. Distributors of public domain or user supported software, other than operators of electronic bulletin board systems, may distribute copies of QBWARE/1 subject to the above conditions only after obtaining written permission from AJM Software. Copyright (c) 1987, AJM Software -Page 9- Product Support If you have any questions or comments about the use of QBWARE/1, please fill out a problem log and send it to us. In your note, describe as completely as possible the problem you are having. Let us know your machine configuration, which routine you are questioning, the version of QBDOS.LIB, and any resident software installed. If possible, include a copy (on paper) of your source code. Describe what steps you take before the problem occurs, and exactly what the program does when it occurs. If you do not provide us with a complete description of the problem there is little we can do to help. We'll do our best to get you past the problem, but if you are not a registered user we do not guarantee to provide support of any kind. Please be patient. We usually respond to registered users within 3 working days at the most. We will provide support to non-registered users at our discretion. It generally depends on how the request is worded and the mental disposition of the staff person assigned to handle requests on that day. Copyright (c) 1987, AJM Software -Page 10- AJM Software Shareware Products AJM Software has developed several software products being released through Shareware channels. These are: QBWARE/1 QBBIOS.LIB The Quickbasic BIOS interface library QBDOS.LIB The Quickbasic DOS interface library QBDOS.LIB The Quickbasic DOS File Mgmt interface library QBWARE/2 QBWINDOW.LIB The Quickbasic windowing system library QBFUNC.LIB The Quickbasic function library QBBIOS.LIB is the Quickbasic - BIOS interface library. This is a collec- tion of assembler routines that can be called from Quickbasic to gain direct access to video, keyboard, disk, and printer services. It also provides a method of determining the computer's configuration, including amount of RAM - conventional, extended, and LIMM expanded, number of hard disks and floppy disks, and more. QBDOS.LIB is the Quickbasic - DOS interface library. This is a collection of assembler routines that can be called from Quickbasic to gain access to most of the DOS facilities. Services include access to the print spooler (DOS V3.00 or higher only), acquisition of an additional 64KB of string space, access to the DOS Video routines, and routines to provide DOS redi- rection in a Quickbasic program, and more. QBDOS.LIB is the Quickbasic - DOS File Manager interface library. This is a collection of assembly language routines that can be called from Quickbasic to gain access to the DOS File Manager facilities. Services include file open, close, and various versions of create, get, set or change current drive or directory, read or write individual sectors, read or write individual records within a file, get or change disk volume names, rename or copy files, get or set file creation dates or times, directly access the disk directory or sub-directories, and more. QBWARE/2 will be released as a Shareware product on December 1, 1987. Copyright (c) 1987, AJM Software -Page 11- Using QBDOS.LIB All of the QBDOS.LIB routines can be accessed via the Quickbasic 'Call' statement. The format of this statement is as follows: Call Function(Parm1%, Parm2%, Parm3$) Function is the name of the routine to be executed. It must be spelled exactly as shown in the following chapters. The parameters to be passed to the routine will also be explained in the following chapters. You must use the exact number of parameters shown in each function description and each parameter must be the type (i.e. character or integer) shown in each function description. Using an incorrect number of parameters or using a parameter of the wrong type (i.e. using character instead of integer) will generally result in the abnormal termination of your program. Usually you will get either a 'String Space Corrupt' error or you will start executing the wrong statements in your program. In any event, it is almost impos- sible to predict the results of these two types of errors, so it is criti- cal that you be very careful in coding the call statements. The parameters passed to QBDOS.LIB routines will be either character or numeric integers. There are no special requirements for passing integers and constants may also be used. There is no functional difference between these two sets of statements: Example 1 Drive$ = "A" 'Indicate drive a Vol$ = "DISK LABEL " 'New volume label Call FlPVol(Drive$, Vol$, Rc%) 'Call QBWARE/1 routine Example 2 Call FlPVol("A", "DISK LABEL ", Rc%) Note that Rc% must not be defined as a constant because the QBDOS routine will return a value in this field and your Quickbasic program cannot access this field if it is defined as a constant. All character fields must be initialized to the proper length before calling a QBDOS.LIB func- tion. Failing to do so may result in a 'String Space Corrupt' condition. The following two examples appear similar but Example 1 will fail and Example 2 will succeed because 'Char$' has been properly initialized. Example 1 (incorrect) Char$ = "" 'clear work field Call FlGDrv(Char$) 'get the current drive Copyright (c) 1987, AJM Software -Page 12- Example 2 (correct) Char$ = space$(1) 'clear work field Call FlGDrv(Char$,) 'get the current drive Including the QBDOS.LIB routines in your programs can be accomplished in a variety of ways. The non-registered user can do one of the following: 1) compile the program from within the Quickbasic interactive develop- ment environment 2) compile the program from the DOS prompt In order to use method 1, place the file QBDOS.EXE in the directory con- taining your Quickbasic files (i.e. QB.EXE and BRUN20.LIB). When starting Quickbasic, enter the following command at the DOS prompt: QB /L QBDOS.EXE You may now use any of the QBDOS.LIB functions in your programs. If you compile your program using the 'Exe' output option, the appropriate QBDOS.LIB functions will be available to the EXE file. In order to use method 2, place the file QBDOS.EXE in the directory con- taining your Quickbasic system files. The following example shows how to create an executable file from the Basic source code in the file 'FILECHK.BAS': QB FILECHK /L QBDOS.EXE; LINK FILECHK; Doing this will create the executable file 'FILECHK.EXE' Additionally, registered users will have the ability to create their own custom user library (see the file BUILDLIB.QBD on the QBDOS.LIB disk for instructions) or they can include the appropriate functions into their program when it is linked. For example, if the program 'TEST.BAS' uses the QBDOS.LIB routines DOSVER and BOOT, an executable file can be created using the following commands at the DOS prompt: QB TEST; LINK TEST DOSVER BOOT; This assumes that all of the files on the QBDOS.LIB disk have been placed into the directory containing the Quickbasic system files. Copyright (c) 1987, AJM Software -Page 13- PRECAUTIONS!!!!!! These routines were designed to used with Quickbasic on an IBM PC or com- patible computer. Using this product with any Basic compiler or inter- preter other than Quickbasic version 2 or 3 may probably not work and may cause loss of data. Using this product on a non-IBM compatible computer will give hit or miss results. Some things will work, some things won't work. The only way to find out is to try. Copyright (c) 1987, AJM Software -Page 14- Miscellaneous DOS Services Function Summary BOOT - Initiate a cold or warm boot DOSCHOUT - Write a string to the standard output device DOSCHRIN - Read a character from the standard input device DOSSTRIN - Read a string from the standard input device DOSRED - Redirect a DOS standard handle DOSPRSC - Print the screen DOSVER - Get the DOS version DOSVRFY - Turn verify mode on and off Copyright (c) 1987, AJM Software -Page 15- BOOT - Initiate a cold or ward boot Usage - Call Boot(Function%) Function% 0 - Perform a warm boot 1 - perform a cold boot Programming notes: There is no return from this function - it restarts the machine. A warm boot is the equivalent of pressing Alt-Ctrl-Del - a cold boot is the equivalent of turning the machine off and then on again. Copyright (c) 1987, AJM Software -Page 16- DOSCHOUT - Write a string to the standard output device Usage - Call DosChOut(Str.Out$) Str.Out$ Text to be written Programming notes: If the standard output device is CON (monitor), the text is written to the current cursor location. Printing control characters(i.e. carriage return, line feeds) will cause the cursor to move accordingly. All data is written in 'raw' mode - this bypasses certain checking that DOS normally would do and increases output speed a little. Do not print chr$(255) as this will cause a keyboard read to occur. This service, like the other DOS keyboard/con services, can be re-directed. Copyright (c) 1987, AJM Software -Page 17- DOSCHRIN - Read a character from the standard input device Usage - Call DosChrIn(Char.In$, Echo%, Rc%) Char.In$ Character returned from the standard input device. Echo% 0 - do not echo to standard output 1 - echo to standard output Rc% 0 - indicates no character was found 1 - indicates character returned in Char.In$ 2 - indicates an extended ASCII character was returned in Char.In$ Programming notes: Extended ASCII characters will not echo. No special action is taken if Ctrl-C or Ctrl-Break is detected. Char.In$ must be initialized to a space. If it is not, the service will fail and a "String Space Corrupt' condition may occur. If an extended ASCII code is entered, Char.In$ will contain the second character of the code. This service, like the other DOS keyboard/con services, can be re-directed. Copyright (c) 1987, AJM Software -Page 18- DOSSTRIN - Read a string from the standard input device Usage - Call DosStrIn(Text.In$, Count%) Text.In$ input string Count% length of input string Programming notes: Use this function only for input of a single string on a screen. The editing characteristics of this service do not lend themselves to full screen input. No extended ASCII codes are allowed by this function. The maximum input length is the length of Text.In$ - 3. For example, if you wanted input with a maximum length of 12 characters, use the following code: Text.In$ = Space$(15) 'Maximum length + 3 call DosStrIn(Text.In$, Count%) End of input is signaled by pressing the [Enter] key. If you type in more than the maximum number of characters, the beep will sound until [Enter] is pressed. No cursor will be displayed while characters are being entered. The characters entered at the keyboard will echo on the monitor at the current cursor position. This service, like the other DOS keyboard/con services, can be re-directed. Copyright (c) 1987, AJM Software -Page 19- DOSRED - Redirect a DOS standard handle Usage - Call DosRed(Device%, FileSpec$, Rc%) Device% Device to redirect 0 - Standard input 1 - Standard output 3 - Standard AUX device 4 - Standard list device Filespec$ Standard ASCIIZ string Rc% Return code Programming notes: See the Appendix in the documentation for QBFILE.LIB for an explanation of return codes. The standard input device is CON, or the keyboard. If you redirect this device to accept from a file, you cannot detect end-of-file. If you play with this device, be prepared to reboot quite a bit while testing - incor- rect handling can easily cause the keyboard to lock up. The standard output device is CON, or the monitor. You can redirect this device either to a file or printer. Once redirected, all PRINT statements will print to FileSpec$. See the sample program TYPER.BAS included with this package. The standard auxiliary device is AUX - generally COM1. The standard list device is PRN - generally LPT1. Unfortunately, Basic does not use the standard list device for LPRINT statements or for PRINT# statements, thereby making redirection of this handle a little less useful than it could be. If FileSpec$ is NUL (i.e. FileSpec$ = ""), DOSRED will reset the device to its default value. these are: Device% Default 0 CON 1 CON 3 AUX 4 PRN If FIleSpec$ is CHR$(255), DOSRED will simply close that handle. This is useful if you're not using DOS 3.3 and you need more than fifteen files open at one time (the Quickbasic limit). Simply close one of the devices, and that allows you to open another file. If you close the standard input Copyright (c) 1987, AJM Software -Page 20- device, be sure to reopen it as you won't be able to get any input from the keyboard. Rumor has it that under DOS 3.3, you can have up to 255 files open at any one time. If FileSpec$ is a disk file, and it already exists, DOSRED will simply write over it. If it does not exist, DOSRED will create it. You must close any disk files used for redirection before terminating your program. Otherwise, the file's directory entry (length) will not be updated and you will not be able to process that file. A file close is done automatically when you issue a reset (FileSpec$ = ""). Copyright (c) 1987, AJM Software -Page 21- DOSPRSC - Print the screen Call DosPrSc Programming notes: This service will print the contents of the screen buffer. It is really a BIOS service, but because of it's usefulness, it is included here. Copyright (c) 1987, AJM Software -Page 22- DOSVER - Get the DOS version Usage - Call DosVer(Version%) Version% the version of DOS currently running Programming notes: Version is returned as an integer. DOS 3.10 would be returned as 310, and so on. To display it properly, use the following code: Call DosVer(Version%) Print Using "#.##";Version%/100 Copyright (c) 1987, AJM Software -Page 23- DOSVRFY - Turn verify mode on and off Usage - Call DosVrfy(Function%) Function% 0 - turn verify off 1 - turn verify on -1 - get status of verify Programming notes: When verify is on, every write request made through DOS will cause DOS to reread the sector just written to insure that it is readable. No verification is done when BIOS is used to write a sector. DOS does NOT perform a verify by checking that the sector written matches the data in the output buffer. It simply insures that the sector written can be read and that it passes the CRC. Verify does add overhead when it is turned on. Use this service when the output media is questionable. When using Function% = -1, DOSVRFY will return a 0 is Function% if Verify is off and a 1 if Verify is on. Copyright (c) 1987, AJM Software -Page 24- The Print Spooler YOU MUST HAVE VERSION 3.XX OF DOS TO USE THESE SERVICES Function Summary DOSPSTAT - Request spooler status DOSPCAN - Cancel all spooled files DOSPDEL - Delete a file from the queue DOSPLST - List all files in the queue DOSPSUB - Submit a file to the queue Copyright (c) 1987, AJM Software -Page 25- DOSPSTAT - Request spooler status Usage - Call DosPStat(Rc%) Rc% 0 - Normal status - okay to use spooler 1 - Spooler is inactive 2 - Spooler unavailable 255 - Invalid request (invalid DOS version) Programming notes: This service simply provides the spooler status. Each service in this section also checks the spooler status. The only good return code is 0. Any of the other return codes indicate that the spooler is not useable. A return code of 1 indicates the spooler is not running, but it could be started from the DOS prompt. A return code of 2 indicates that the spooler is not active and it cannot be started because some other process has captured the spooler interrupt. A return code of 255 indicates that the wrong version of DOS is installed - version 3.00 or higher is needed. See Appendix A for a discussion on starting the print spooler. Copyright (c) 1987, AJM Software -Page 26- DOSPCAN - Cancel all spooled files Usage - Call DosPCan(Rc%) Rc% Return code Programming notes: See Appendix A for an explanation of return codes. This service will delete all files from the print queue. Please remember that most printers have a print buffer - some as large as 256k. This function will not clear the print buffer. Copyright (c) 1987, AJM Software -Page 27- DOSPDEL - Delete a file from the queue Usage - Call DosPDel(FileSpec$, Rc%) Filespec$ ASCIIZ string Rc% Return code Programming notes: Filespec$ should be the name of a file in the print queue in ASCIIZ for- mat. ASCIIZ format is simply the file name followed by a CHR$(0), for example: Filespec$ = "C:\SPOOLDIR\TEXTFILE.DAT" +CHR$(0) You must use the entire filename (including drive and path) when deleting a file from the queue. See Appendix A for an explanation of return codes. This service will delete a files from the print queue. Please remember that most printers have a print buffer - some as large as 256k. This function will not clear the print buffer, so if the deleted file is print- ing, it will continue to print until the buffer is emptied. Copyright (c) 1987, AJM Software -Page 28- DOSPLST - List all files in the queue Usage - Call DosPLst(File.Array$(0), Rc%) File.Array$ Array that will contain the names of all the files in the print queue Rc% Return code Programming notes: See Appendix A for a explanation of return codes. File.Array$ must be initialized and have the proper number of elements prior to calling DOSPLST. Failing to initialize it properly will cause DOSPLST to fail and probably freeze up your computer. The maximum number of entries depends on what parameters were used when the print spooler was started. The absolute maximum is 32. I would strongly recommend that you plan for the maximum. The following code seg- ment shows the proper method of using DOSPLST. MaxQueue% = 31 'This is really 32 entries when 'using Option Base 0 Dim File.Array$(MaxQueue%) 'plan for max number of entries For X% = 0 to MaxQueue% 'initialize the array File.Array$ = Space$(64) 'max length of a filename Next Call DosPLst(File.Array$(0), Rc%) 'go get list If Rc% <> 0 then goto YOUR.ERROR.ROUTINE Copyright (c) 1987, AJM Software -Page 29- DOSPSUB - Submit a file to the queue Usage - Call DosPSub(FileSpec$, Rc%) FileSpec$ ASCIIZ string Rc% Return code Programming notes: FileSpec$ is the name of the file to be submitted to the print queue. See Appendix A for an explanation of return codes. The file is placed at the tail of the print queue. It will not print until all other files ahead of it have already printed. There is no way of prioritizing the files with the services presented here. Copyright (c) 1987, AJM Software -Page 30- DOS Memory Management PLEASE READ APPENDIX B BEFORE USING ANY OF THESE SERVICES Function Summary DOSMALLC - Allocate additional memory DOSMFREE - Free memory DOSMGET - Get some data from allocated memory DOSMPUT - Put some data in allocated memory Copyright (c) 1987, AJM Software -Page 31- DOSMALLC - Allocate additional memory Usage - Call DosMAllc(Block, MemSize%, Element.Size%, Rc%) Block% Reserved for future use MemSize% Amount of memory to acquire (in Kilobytes) valid ranges are 1-64 Element.Size% Size of each array element. Rc% Return code Programming notes: See Appendix B before using this service. Return code is explained in Appendix B. MemSize% is the memory size in KB - 64 would get 64,000 additional bytes. The area of memory returned by this service is initialized to nulls - CHR$(0). Only 1 area of memory can be allocated at any one time. If this service is attempted twice without an intervening call to DOSMFREE, the second call to DOSMALLC will fail. This service is the equivalent of the BASIC function DIM when used with a dynamic array. Copyright (c) 1987, AJM Software -Page 32- DOSMFREE - Free memory Call DosMFree(Block%, Rc%) Block% Reserved for future use Rc% Return code Programming notes: See Appendix B before using this service. Return code is explained in Appendix B. This service will free all memory obtained with DOSMALLC. This service is the equivalent of the BASIC function ERASE when used with a dynamic array. Copyright (c) 1987, AJM Software -Page 33- DOSMGET - Get some data from allocated memory Usage Call DosMGet(Block%, Index%, Text$, Rc%) Block% Reserved for future use Index% Array element number to retrieve Text$ String that will contain the data returned from memory Rc% Return code Programming notes: See Appendix B before using this service. Return code is explained in Appendix B. Text$ must be initialized to the proper length prior to using this ser- vice. It's length must equal the value of Element.Size% used in DOSMALLC. Index% the offset into the array where the requested data resides. The minimum value for Index% is 0 - the maximum value is determined by the following formula: MaxIdx% = Int(Max.Size%/Element.Size% *1000) - 1 Copyright (c) 1987, AJM Software -Page 34- DOSMPUT - Put some data in allocated memory Usage Call DosMPut(Block%, Index%, Text$, Rc%) Block% Reserved for future use Index% Array element number where data will be placed Text$ String containing the data to be placed into the array Rc% Return code Programming notes: See Appendix B before using this service. Return code is explained in Appendix B. The length of Text$ cannot exceed the value of Element.Size%. Index% the offset into the array where the data will be placed. The minimum value for Index% is 0 - the maximum value is determined by the following formula: MaxIdx% = Int(Max.Size%/Element.Size% *1000) - 1 Copyright (c) 1987, AJM Software -Page 35- Appendix A The Print Spooler Version 3.00 of DOS brought with it a remarkable new program - the print spooler. The spooler is remarkable because it allows you to print files in the background while the computer is free to do other tasks. It is somewhat limited in that it does automatically capture data going to the printer and spool it for you and it must be used from the DOS prompt. In order to use it, you must write your report to a file and subsequently go to the DOS prompt and submit it to the print queue - either manually or through a batch file. The services provided in QBDOS.LIB will assist in incorporating the spooler into any Quickbasic system. You must still write each report to a file, but we can, with DOSPSUB, submit the file to the print queue directly from a Quickbasic program. In order to use QBDOS.LIB spooler service, we must start the spooler before your Quickbasic basic program executes. The spooler can be started from the DOS prompt or from your AUTOEXEC.BAT file (any BAT file will do). The spooler program is called PRINT.EXE and is available on your DOS ver- sion 3.XX diskettes. When starting the spooler, there are several options that can be used. These are: /D Device that all files will be printed on - if omitted, the spooler will prompt you for a device name /Q Maximum number of files that can be in the print queue - the default is 4 and the absolute maximum that can be used is 32 /B Buffersize of the internal buffer used by the spooler - the default is 512 bytes - we always use 2048 bytes, but the correct value will depend on overall system usage /S Timeslice for the spooler - this defines the number of clock ticks that the spooler will use - the default is 8 and the values can range from 1-255 /M Specifies the maximum number of clockticks that the spooler will use to print a character - values can be 1-255 and the default is 2 /U Specifies the number of clockticks that the spooler will wait for the printer to become available - values can range from 1-255 and the default is 1 Copyright (c) 1987, AJM Software -Page 36- The command PRINT /D:LPT1 /B:2048 /Q:32 will activate the spooler with an internal buffer of 2048 bytes and cause all output to be spooled to LPT1. The maximum number of files that can be in the queue at one time is 32. Once this is completed, the routines in QBDOS.LIB can be used. Return codes from the spooler are as follows: Rc Reason 0 Successful 1 Spooler inactive 2 Spooler inactive (DOSPSTAT only) 2 File not found 3 Path not found 4 Too many open files 5 Access denied 8 Queue full 9 Spooler busy 12 Name too long 15 Invalid drive 255 Invalid DOS version Copyright (c) 1987, AJM Software -Page 37- Appendix B Using the DOS Memory Services General info The Dos Memory Services provided in QBDOS.LIB will allow you to allocate an array of up to 64,000 characters in length. This array is handled like text data, but unlike BASIC, QBDOS.LIB does not allow variable length strings. This data resides outside of the Quickbasic data segment, so it has no effect on the amount of string space normally provided by Quickba- sic. This array is handled a little bit differently than a Quickbasic array would be. Let's look at some examples. In Quickbasic, we could allocate an array and initialize a single element with the following code segment: Option Base 0 Dim Array$(400) Array$(0) = "This is the first element of the array" Using the services in QBDOS.LIB, we could do this: Mem.Size% = 64 'Allocate 64,000 bytes Element.Size% = 100 'Need element size because QBDOS.LIB does not 'support variable length text Call DosMAllc(Block%, Mem.Size%, Element.Size%, Rc%) If Rc% <> 0 then Goto Error.Routine Text$ = "This is the first element of the array" Index% = 0 Call DosMPut(Block%, Index%, Text$, Rc%) In the Quickbasic example, we first allocate enough memory for 400 items in the array called Array$ (Note that this doesn't mean that you can actu- ally use all 400. If you tried to initialized each element of Array$ to 200 spaces, your program would run out of string space long before you completed the initialization). All this actually does is set aside 1600 Copyright (c) 1987, AJM Software -Page 38- bytes within Quickbasic. This 1600 bytes is used as a series of 'string descriptors' - you can read the Quickbasic manual for a discussion of string descriptors. Next, we assign a value to the first element in the array. Quickbasic allocates some space in it's own data segment for this value and updates the string descriptor accordingly. The descriptor con- tains the length of the string and it's location within the Quickbasic data segment. In the QBDOS.LIB example, we first need to allocate some space. The amount of space needed is 64,000 characters, or bytes. This is done by setting Mem.Size = 64 Next, because QBDOS.LIB will not support variable length text, we need to determine the length of each element. For all practical purposes, this is the length of the longest element that we will place into the array. Next we allocate space for the array using DOSMALLC. This service actually allocates the entire 64,000 bytes. In order to initialize on of the ele- ments of our new array, all we need do is specify the element number, or index, and the text itself - DOSMPUT will do the rest. Keep in mind that if the length of the Text$ that you're storing to the array is longer than Element.Size%, DOSMPUT will not store the data and it will pass a return code of 252 back to the calling program. If the length of Text$ is less or equal to than Element.Size%, DOSMPUT will store all of the text. Text$ can be retrieved from the array by using the same technique with DOSMGET. DOSMGET will always return a string of length Element.Size%. If the length of the original string stored with DOSMPUT was less than Ele- ment.Size%, DOSMGET will still return a string of length Element.Size%. The back end of the string will be padded with nulls (CHR$(0)). If you transfer control from the program that allocates memory to another Quickbasic program, you may still be able to use the array allocated in the first program. If the first program "CHAIN"'s to the second program, the array allocated in the first program will be intact - no data will be lost. Additionally, the special linking requirements explained later in this Appendix apply only to the first program. If, however, the first program "RUN"'s the second program, then the array allocated in the first program is lost. If the second program needs to allocate memory, then it must be linked using the guidelines discussed later in this Appendix. Copyright (c) 1987, AJM Software -Page 39- Who can use the memory allocation services? Memory is a severely limited resource in most computers from large IBM mainframes to the PC. Whether or not you can use the QBDOS.LIB memory services depends on several factors. We'll discuss each of these factors in detail to help you decide whether or not QBDOS.LIB is viable for you. The first constraint is the amount physical conventional memory installed on your computer - this does not include extended or expanded memory. The maximum amount of conventional memory that can be installed in any DOS computer is, of course, 640,000 bytes. The rules to follow here are: - If you have less than 256K of memory, you probably cannot run applications that use the QBDOS.LIB memory services - If you have 256K of memory, you MIGHT be able to run these applications, but you probably cannot write your own applica- tions. The Quickbasic integrated development requires to much memory to allow testing. -If you have more than 256K of memory, you can probably run and test applications written with QBDOS.LIB memory management facil- ities. Read on for further information. The next constraint is the amount of memory used by things other than Quickbasic. DOS requires a minimum of around 26K - and that is for a plain vanilla DOS. I generally install several drivers and have my files and buffers parameters set pretty high so DOS requires 55K on my machine. If you have a great deal of TSR's (SideKick for example) installed, you may be giving up a lot of memory to them - the more memory used by TSR's, the less available to Quickbasic and QBDOS.LIB. Both DOS and TSR's decrease the amount of memory available. If you're having a problem using QBDOS.LIB and you have TSR's installed, try removing them. The next constraint is the amount of memory used by Quickbasic. The fig- ures presented here have been arrived at by analysis performed by us and in no way reflect any information received by Microsoft. There are sev- eral factors that determine the amount of memory that a Quickbasic program needs to execute. These are: - The amount of code that you write. Quickbasic needs about 68K of memory for the its' own routines. Any code that you write would be over and above this 68K. Copyright (c) 1987, AJM Software -Page 40- - The data area used by Quickbasic is always 64K - no more, no less. - The size of the user library increases memory requirement by the size of the code segments in the library. - Communication programs will require storage for buffers. This, of course, is allocated by the programmer. - All remaining memory gets allocated to the far heap. If you use large numeric arrays, they would be allocated here. This is the area of memory used by QBDOS.LIB. From this info, we can see that a very simple one-line Quickbasic program will need about 132K to run. An approximation of memory requirements can be calculated with: Data segment size 64K + QB runtime library 68K + Size of far arrays ?? + (1) User library code size ?? + (2) Size of EXE file ?? + (3) Size of communication buffers ?? + (4) = memory requirements Add about 124K if you're running programs out of the QB editor. For programs compiled with the /o option, do not include the QB runtime library size. (1) Far arrays are large numeric arrays defined in your program. You can determine size using the following: Integer arrays - Size = Number of elements * 2 Single precision - Size = Number of elements * 4 Double precision - Size = Number of elements * 8 (2) This is tough, but to be on the safe side, just use the size of your USERLIB.EXE file (or whatever your user library is named). (3) This is simply the size of the EXE file as reported by the DOS dir command. (4) This one is easy because you as the programmer allocate these with the /c:buffersize parameter. Copyright (c) 1987, AJM Software -Page 41- If, after adding these numbers together, we come up with a memory require- ment that is close to the size of memory installed in that computer, you probably cannot use the memory management facilities in QBDOS. If there is room in your program, read on (Remember, when you run a program from the Quickbasic editor, add about 124K). Preparing to use the memory allocation services When a Quickbasic program is linked, the linker tells DOS the minimum and maximum amounts of memory required by the program. When you execute the program, DOS will attempt to allocate the maximum amount of memory needed by the program. For Quickbasic programs, this maximum is always all of available memory. Before using the memory allocation services, we must first adjust the amount of memory that DOS allocates for the program. This can be done in three ways: 1) When linking your Quickbasic program, use the CP parameter to limit maximum memory size. You can tell the assembler how much memory to allocate in units of 16 byte paragraphs. For example, if we wanted a program to use 256k, we would link it like this: qb testprog; link testprog /cp:16000 We can determine the number of paragraphs by taking the memory size and dividing by 16 (256,000 / 16 = 16000) 2) For those of you who have Microsoft's MASM, you can use the EXEMOD utility. EXEMOD will do the same thing that the CP parameter of link does except that we must specify the paragraph count in Hexa- decimal. If we wanted a program to use 256k of memory, we could do this: qb testprog; link testprog; exemod testprog /max 4000 4000 is about the number of paragraphs, in hex, that we need to get 256K - it's actually a little high, but it's easier to remember than 3E80. 3) The program QBTMOD.BAS, provided with QBDOS.LIB, will change the maximum memory requirement to 256K. Source code is provided so you can modify it as you wish. Copyright (c) 1987, AJM Software -Page 42- Using the memory allocation services in the Quickbasic editor is a little trickier. We must take the following steps in order to do this. 1) Make a BACKUP of QB.EXE 2) Make another BACKUP of QB.EXE 3) Do one of the following: - EXEMOD QB /MAX 4000 (if you have EXEMOD) - QBTMOD QB /MAX 16000 This will allow you to execute DOSMALLC once while in the Quickbasic edi- tor. When you start Quickbasic, it will not allocate all of memory, how- ever, if you run a program (Ctrl-R) or SHELL from the editor, when you return to Quickbasic, it acquires all available memory. This means that you can only run DOSMALLC once while in the editor. If you need to run it again, you must first exit Quickbasic, and then start it again. This does cause some problems in debugging our programs, but if you need the additional string space and you don't have expanded memory, then your options are limited. NOTE - IF ALL OF THIS IS TOO MUCH TO SWALLOW, WRITE US ABOUT OUR QUICKBASIC - LIMM EXPANDED MEMORY INTERFACE. Copyright (c) 1987, AJM Software -Page 43-