Category : BASIC Source Code
Archive   : QBDOS.ZIP
Filename : QBDOS.DOC

 
Output of file : QBDOS.DOC contained in archive : QBDOS.ZIP















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-






  3 Responses to “Category : BASIC Source Code
Archive   : QBDOS.ZIP
Filename : QBDOS.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/