POINT Software Programming/PPROG1.ISO/basic/pbasmlib/dos.doc

Text File | 1994-02-12 | 42.0 KB | 1,191 lines

PBASMLIB Assembly Language Routines for PB3C
Version 1.0
MS-DOS Function Interface (DOS.ASM)
(C) Copyright 1994 by Tim Gerchmez
All Rights Reserved.

This module contains many routines that provide a low-level interface
to MS-DOS functions.  It is contained in the PBASMLIB.PBL library, and
the routines will be immediately accessible to your programs by including
the statements $INCLUDE "PBASMLIB.INC" and $LINK "PBASMLIB.PBL" at the top
of your programs.

================================================================================
function bootdrive

DOS 4+ only - Returns drive system was booted from.

bootdrive: Returns boot drive number (1=A, 2=B...)

Example: print bootdrive

================================================================================
function breakflag

Returns the status of the DOS BREAK flag, which affects
CTRL-C checking during DOS function calls. See SETBREAK.

breakflag: Returns 0 if BREAK=OFF, or 1 if BREAK=ON.

Example: b%=breakflag

================================================================================
function bytesfree(d%)

Same as DRIVESPACE - used as a synonym in case you find
the command BYTESFREE easier to remember.  See DRIVESPACE
for details.

d%: Set to disk to check (0=current, 1=A, 2=B...)
bytesfree: Returns bytes free on specified drive

Example: print bytesfree(1)

================================================================================
sub changedir(p$,er%)

Sets the specified directory to be the current directory.
Same as PB's CHDIR command, but returns an error code instead
of forcing you to trap errors with ON ERROR.

p$: Set to path of directory to change to
er%: Returns error code, or 0 if OK.

Example: changedir p$,er% 'er% = 0 if ok or error code.

================================================================================
function charin$

Reads a character from the keyboard without echoing it
to the display.  If no character ready, waits for one.
No CTRL-C checking, and may be redirected.  Call twice
to read extended ASCII codes (first call will return 0).

charin$: Returns character user typed

Example: print charin$

================================================================================
function charinecho$

Inputs a character from the keyboard and echos it
to the display.  If no character is available, waits
until one is.  Input can be redirected.  Call twice
to read extended ASCII codes (first call will return
a zero).  Note: PowerBASIC's cursor position is NOT
updated by this routine (just the DOS/BIOS cursor).

charinecho$: Returns with character entered.

Example: a$ = charinecho$

================================================================================
sub charout(a$)

Outputs a character to the currently active video
display, or standard output device if redirected.

a$: Set to single character to display.  If string is
    longer than one character, only the first character
    will be displayed.

Example: charout "A"

================================================================================
sub closefile(h%)

Closes a file previously opened with OPENFILE or MAKEFILE.
Use the handle returned by these routines.

h%: Set to handle returned by OPENFILE or MAKEFILE

Example: closefile h1%

================================================================================
sub commitfile(h%)

Forces all data in MS-DOS buffers to be written to a device,
and updates the directory entry if a file.  This has the
same effect as flushing, closing and reopening a file again.

h%: Set to handle of file to commit

Example: commitfile h%

================================================================================
function countryinfo$

Returns a string containing information regarding the current
MS-DOS country-dependent information (MS-DOS 2+, PC-DOS 3+ only).

countryinfo$: Returns a string containing the following info
              (use MID$ to separate out information):
Bytes 1-2: date format (0=USA MDY, 1=Europe DMY, 2=Japan YMD)
Bytes 3-7: ASCIIZ currency symbol string
Byte 8 :   Thousands separator character
Byte 10:   Decimal separator character
Byte 12:   Data separator character
Byte 14:   Time separator character
Byte 16:   Currency format
Byte 17:   Number of digits after decimal in currency
Byte 18:   Time format (0=12-hour, 1=24-hour clock)
Bytes 19-22: Case-map call address
Byte 23:   Data list separator character

Example: ci$ = countryinfo$
         print mid$(ci$,23,1) 'Print data list separator (USA=comma)

================================================================================
function createfile(f$)

Creates/opens a new file using the designated path\filename,
and returns a handle to the file allowing subsequent access
with the other DOS file commands.  If the specified file
already exists, this routine will fail without affecting the
specified file.  To truncate the specified file to zero length
if it already exists, use MAKEFILE instead.  To open an
existing file, use OPENFILE instead.

f$: Set to path\filename of new file to create
createfile: Returns handle to the file, or 0 if error condition

Example: handle% = createfile(f$)
         if handle% = 0 then print "Error creating"

================================================================================
function curdrive

Returns the drive code of the current (default) drive
(0=A, 1=B, 2=C, etc...).  See SETDRIVE.

Example: print curdrive

================================================================================
function curdrivesize

Returns the size (in bytes) of the default (current)
disk drive (this is not free space, but TOTAL space
available).

curdrivesize: Returns capacity of drive in bytes

Example: print curdrivesize

================================================================================
function curdrivespace

Returns bytes free on current (default) drive.
This is actual free space remaining.  To check
total space, see CURDRIVESIZE.

Example: print curdrivespace

================================================================================
function datecode(yr%,mo%,dy%)

Translates a given date provided (year, month and day)
into the word-length code DOS uses to store file date
on a disk drive.  Can also be used to translate a date
to a packed format for storage elsewhere.

yr%: Set to year (1980-2099)
mo%: Set to month (1-12)
dy%: Set to day (1-31)
datecode: Returns word-length date encoded.

Example: dc??=datecode(1993,9,12)

================================================================================
sub decodedate(code??,yr%,mo%,dy%)

Decodes a DOS-encoded date (used for file date storage)
back into a year-month-day format (see DATECODE).
This can be used to decode any date encoded with DATECODE.

code??: Set to date code (see DATECODE)
yr%: Returns year (1980-2099)
mo%: Returns month (1-12)
dy%: Returns day (1-31)

Example: decodedate c??,yr%,mo%,dy%

================================================================================
sub decodetime(code??,hr%,mn%,sc%)

Decodes a DOS-encoded time (used for file time storage)
back into an hour/minutes/seconds format (see TIMECODE).
This can be used to decode any time encoded with TIMECODE.

code??: Set to time code (see TIMECODE)
hr%: Returns hour (0-23)
mn%: Returns minute (0-59)
sc%: Returns second (0-59)

Example: decodetime c??,h%,m%,s%

================================================================================
sub disabledrive(d%)

Disables the specified drive completely, disallowing access
until drive is reenabled with enabledrive.  DOS 5+ ONLY.

d%: Set to drive to disable (0=A, 1=B...)

Example: disabledrive 0

================================================================================
function dosdataseg

Returns the data segment of MSDOS.SYS/IBMDOS.COM.

dosdataseg: Returns DOS data segment

Example: print dosdataseg

================================================================================
function doserr$(en%)

Returns text describing the extended DOS error code passed
to this routine.  Use the number returned from other DOS routines
in er%.  Unidentified errors will return "DOS Function Error."

en%: Set to DOS error number
doserr$: Returns text describing DOS error code

Example: sethandlecount nhd%,er% 'See SETHANDLECOUNT
         print doserr$(er%) 'Prints DOS error returned (0="OK")

================================================================================
sub dosflush

Flushes all open files, writing data to disk, without closing
those files.  Same as PB FLUSH command, except that a file
number cannot be specified - all data will always be flushed.

No parameters.

Example: dosflush

================================================================================
function dosinput$(mx%)

Uses a DOS function to input a string from the keyboard.  The
characters are echoed to the display, and input may be redirected.
Cursor might be hidden during input; use LOCATE ,,1 before calling
if you want the cursor visible when the user is inputting data.

mx%: Set to maximum allowable length of input (1-255)
dosinput$: Returns inputted string (exact length user entered).
           User input is terminated with a carriage return.

Example: i$ = dosinput$(8)  'Get 8 chars. max

================================================================================
function dosinstat

Same as INSTAT, but uses a DOS function to detect if there
are any keys in the keyboard buffer.

dosinstat: Returns 0 if no characters, -1 if at least one
           character is available in the keyboard buffer.

Example:  while not dosinstat:wend  'wait for a keypress
        kbdclr  'Clears keyboard buffer - see KBDCLR

================================================================================
sub dosprint(a$)

Prints a string using a DOS interrupt.

a$: Set to string to print, which should be terminated with
    a "$" character to mark the end of the string for DOS.  If
    you forget the $, DOS may print more than you had anticipated.
    Obviously the string cannot contain a "$" character anywhere
    except at the end.  No carriage return is printed at the end
    of the string, and the PowerBASIC cursor is NOT updated (the
    DOS cursor is, however, so the next call will print right after
    the end of where the last call left off).

Example: dosprint "Hello!$"

================================================================================
function drivesize(d%)

Returns the size (in bytes) of the specified drive (this
is not free space, but TOTAL space available).  If error
(disk not in drive, etc) returns 0.

d%: Set to number of drive to check (0=default, 1=A, 2=B...)
drivesize: Returns capacity of drive in bytes

Example: print drivesize(0)

================================================================================
function drivespace(d%)

Returns bytes free on specified drive.  This
is the actual free space remaining.  To check
total space available if disk were empty, see
DRIVESIZE.  See BYTESFREE for another way to check
bytes free on specified drive (commands are identical).

d%: Set to drive to check (0=current, 1=A, 2=B, 3=C...)
drivespace: Returns bytes free on specified drive.

Example: print drivespace(1)

================================================================================
function driveused(d%)

Calculates number of bytes USED out of the total available
for the specified drive.  For example, on a 10 meg disk, if
there were exactly 3 megs free, this function would return
7168000 (7 megabytes used).

d%: Set to drive number to check (0=default, 1=A, 2=B...)
driveused: Returns number of bytes used on specified drive

Example: print driveused(0)

================================================================================
sub enabledrive(d%)

Enables the specified drive, after disabling with DISABLEDRIVE.
MS-DOS 5+ ONLY.

d%: Set to drive to enable.

Example: enabledrive 0

================================================================================
function fileattrib(f$)

Returns the attributes of a file.  Identical to PB's ATTRIB
function, but does not require the use of ON ERROR to trap
errors.  Not related to PB's FILEATTR command.

f$: Set to path\filename to get attributes for
fileattrib: Returns file attributes (-1 if error):
Bit 5 = Archive
Bit 4 = Subdirectory
Bit 2 = System
Bit 1 = Hidden
Bit 0 = Read only

Example: print fileattrib(f$)

================================================================================
sub findfirst(f$,atr%,er%)

Given a file spec, searches the default or specified directory
for the first matching file, and returns file information in the
current DTA.  Use GETDTA to get the address of the current Disk
Transfer Area.  You can use the default DTA, but it's recommended
that you set up your own DTA and use it, then use SETDTA afterwards
to restore the address of the original DTA (see example below).

f$: Set to filespec of file to search for
atr%: Set to attribute(s) to use in search (see FILEATTRIB for
      attribute list)
er%: Returns 0 if found, or error code if not found.

DTA layout:
Bytes 0-20 = Reserved
Byte 21 = Attribute of matched file
Bytes 22-23 = File Time:
              Bits 0bh-0fh = hours (0-23)
              Bits 05h-0ah = minutes (0-59)
              Bits 00h-04h = 2-sec increments (0-29)
Bytes 24-25 = File Date:
              Bits 09h-0fh = year (relative to 1980)
              Bits 05h-08h = month (1-12)
              Bits 00h-04h = day (1-31)
Bytes 26-29 = File Size
Bytes 30-42 = ASCIIZ filename and extension

Example: type    dtatype  'Set up for DTA type
            filler as string * 21
            attribute as byte
            filetime  as word
            filedate  as word
            filesize  as dword
            filename  as string * 13 'String terminated with 0 byte
         end type
         dim dta as dtatype 'Set up for new DTA
         getdta s1??,o1?? 'Get current DTA address and keep it for later
         setdta varseg(dta),varptr(dta) 'Set new DTA
         f$="c:\*.exe":atr%=0 'Find "regular" *.exe files in C:\
         findfirst f$,atr%,er% 'if er%=0, dta variable now contains file data
         if er%=0 then print dta.filename 'Example of working with data
         'work with more data here, use FINDNEXT, etc...
         setdta s1??,o1?? 'Return to old DTA setting when done

================================================================================
sub findnext(er%)

Assuming a previous successful call to FINDFIRST (er%=0),
finds the next matching file in the previously specified
directory.  See FINDFIRST for example of setting up a new DTA
and finding files.  Using this function assumes that the previous
call to FINDFIRST contained one or more wildcard characters
in the filespec (f$).

er%: Returns 0 if file found, and current DTA area filled
     with file data, or errorcode if file not found.

Example: findnext er%  'er% will = 0 if another matching file found.

================================================================================
sub getcmosdate(cn%,yr%,mo%,dy%,rs%)

Obtains the current date from the CMOS clock chip.
Similar to GETDATE, but gets the date from the CMOS
chip directly, rather than the system date.

cn%: Returns century (19-20)
yr%: Returns year
mo%: Returns month
dy%: Returns day
rs%: Returns 1 if CMOS clock is running, or 0 if stopped
     (Battery is drained, or no CMOS clock).

Example: getcmosdate cn%,yr%,mo%,dy%,rs%

================================================================================
sub getcmostime(hr%,mn%,sc%,dst%,rs%)

Obtains the time of day from the CMOS chip clock.
Similar to GETTIME, but gets the time from the CMOS
chip directly, rather than the system time.

hr%: Returns hours (0-23)
mn%: Returns minutes (0-59)
sc%: Returns seconds (0-59)
dst%: Returns 0 if standard time, 1 if daylight savings time
rs%: Returns 1 if clock is running, or 0 if stopped (battery
     drained or other CMOS problem, or no CMOS clock).

Example: getcmostime hr%,mn%,sc%,dst%,rs%

================================================================================
sub getdate(yr%,mo%,dy%,dwk%)

Obtains the system day of the month, day of the week,
month and year, using an MS-DOS call.

yr%: Returns year (1980-2099)
mo%: Returns month (1-12)
dy%: Returns day (1-31)
dwk%: Returns day of the week (0=Sunday, 1=Monday...)

================================================================================
sub getdatime(h%,yr%,mo%,dy%,hr%,mn%,sc%)

Gets the date and time directory settings for
a file.  File must be opened first using OPENFILE
or one of the PB open commands.  Erroneous values will
be returned if an unopened or incorrect handle is used.

h%:  Set to handle of previously opened file
yr%: Returns year of file (1980-2099)
mo%: Returns month of file (1-12)
dy%: Returns day of file (1-31)
hr%: Returns hour of file (0-23)
mn%: Returns minutes of file (0-59)
sc%: Returns seconds of file (0-59) (Not displayed in some DOS versions)

Example: open "i",#1,"filename" 'Open file
         h% = fileattr(1,2) 'Get DOS file handle
         getdatime h%,yr%,mo%,dy%,hr%,mn%,sc% 'Get file date/time data

================================================================================
sub getdta(sg??,ofs??)

Gets the current address of the disk transfer area (DTA), which
is used for osme DOS disk-related functions, including the
directory search functions.  See SETDTA.

sg??:  Returns segment of current Disk Transfer Area
ofs??: Returns offset of current Disk Transfer Area

Example: call getdta(sg??,ofs??)

================================================================================
sub getindos(sg??,ofs??)

Gets the segment and offset address of the INDOS flag, which
is incremented when a DOS function is called and decremented
at the end of the call.

sg??:  Returns segment of DOS INDOS flag
ofs??: Returns offset of DOS INDOS flag

Example: getindos sg??,ofs??

================================================================================
sub getswitchchar(ch%)

Gets the DOS switch character setting, which is used for
command line switches.  Use SETSWITCHCHAR to change the
current switch character.

ch%: Returns ASCII value of the current DOS switch character.

Example: getswitchchar ch%
         print chr$(ch%) 'Displays DOS switch character

================================================================================
sub gettime(hr%,mn%,sc%)

Obtains the time of day from the system (DOS) clock.

hr%: Returns hours (0-23)
mn%: Returns minutes (0-59)
sc%: Returns seconds (0-59)

Example: call gettime(hr%,mn%,sc%)

================================================================================
sub getvector(i%,sg??,ofs??)

Obtains the address of the current interrupt handler
routine for the specified machine interrupt.  See SETVECTOR.

i%: Set to interrupt number (0-255) to get
sg??: Returns segment of handler for interrupt specified in i%
ofs??: Returns offset of handler for interrupt specified in i%

Example: getvector 32,sg??,ofs??

================================================================================
sub getver(mj%,mn%)

Returns the version of MS-DOS currently in use.

mj%: Returns major version number (6 for DOS 6.20)
mn%: Returns minor version number (20 for DOS 6.20)

Example: getver mj%,mn%

================================================================================
function isspooler

Checks if the DOS PRINT.COM print spooler is installed,
and returns 0 if no, or -1 if yes.  Use this command before
calling any of the other PBASMLIB SPOOL commands.

isspooler: Returns 0 if PRINT.COM not installed, -1 if installed,
           257 if error condition (not OK to install).

Example: if isspooler = -1 then print "Print Spooler Ready"

================================================================================
sub kbdclr

Clears the keyboard buffer, removing all pending keystrokes.

No parameters.

Example: kbdclr

================================================================================
sub killfile(f$,er%)

Erases a file.  Similar to PB's KILL command, but can only
erase one file at a time (does not accept wildcards), and
returns an error code instead of forcing you to trap errors.

f$:  Set to path\filename to delete (no wildcards)
er%: Returns 0 if file deleted, or error code if unsuccessful.

Example: killfile f$,er% 'er% = 0 if file killed successfully

================================================================================
function lastdoserr

Returns the extended error code for the last MS-DOS error
encountered.  This could be from a DOS interrupt called from
SHELL, by PowerBASIC, or that you called yourself.  Error number
will stay the same until a new INT 21h DOS error occurs.

lastdoserr: Returns extended error code of last DOS error
            encountered.  See DOSERR$

Example: print doserr$(lastdoserr) 'Returns text of last error

================================================================================
sub makedir(p$,er%)

Creates a directory using the specified path and drive.
Same as PB's MKDIR command, but returns an error code rather
than causing a PB error condition.

p$:  Set to drive\path to create
er%: Returns error code or 0 if ok

Example: makedir p$,er% 'er%=0 if directory created successfully

================================================================================
function makefile(f$)

Creates/opens a new file using the designated path\filename,
and returns a handle to the file allowing subsequent access
with the other DOS file commands.  If the specified file
already exists it is truncated to zero length, so be careful.
You can create a file more safely using CREATEFILE instead,
which fails if the specified filename exists rather than
truncating it to zero length.
To open an existing file, use OPENFILE instead.

f$: Set to path\filename of new file to create
makefile: Returns handle to the file, or 0 if error condition

Example: handle% = makefile(f$)
         if handle% = 0 then print "Error creating"

================================================================================
function malloc(np??,iseg??)

Allocates a block of memory from DOS and returns a
pointer to the beginning of the allocated area.  Make
sure to use SETMEM in PB to deallocate some of PB's memory
first before attempting to allocate memory using this function.
See MRELEASE and MRESIZE.

np??: Set to number of paragraphs (16-byte blocks) of memory
      to allocate.
iseg??: Returns initial segment of allocated block(s) if
        successful, or size of largest available block if not
malloc: Returns -1 if function successful, 0 if not.

Example: if malloc(10,iseg??) then print "Alloc Successful"
         'Allocates 160 bytes, initial seg returned in iseg??

================================================================================
function mallocstrat

Obtains the code indicating the current MS-DOS strategy
for allocating memory blocks (see MALLOC and related routines).
See also SETMALLOC to change memory allocation strategy.

mallocstrat: Returns the following:
0 = First Fit - MS-DOS searches available memory blocks from
    low to high addresses, assigning the first block large
    enough to satisfy the MALLOC request. (Optimized SPEED).
    This is the default MALLOC strategy.
1 = Best Fit - MS-DOS searches all available memory blocks
    and assigns the smallest available block that will satisfy
    the request, regardless of position (Optimized SIZE)
2 = Last Fit - MS-DOS searches the available memory blocks from
    high to low addresses, assigning the highest one large enough
    to satisfy the MALLOC request.

Example: ms% = mallocstrat

================================================================================
function mrelease(sg??)

Releases a block of memory previously allocated with MALLOC.

sg??: Set to segment of block to release (iseg?? in MALLOC)
mrelease: Returns -1 if function successful or 0 if not.

Example: if mrelease(sg??) then print "Memory Released."

================================================================================
function mresize(nbs??,sg??,mbs??)

Dynamically shrinks or extends a memory block.  Use in
conjunction with MALLOC and MRELEASE to dynamically allocate,
deallocate and resize blocks of memory.

nbs??: Set to new block size in paragraphs
sg??:  Set to segment of block to be modified (iseg?? in MALLOC)
mbs??: If error, Returns maximum block size available (paragraphs)
mresize: Returns -1 if ok or 0 if error

Example: if mresize(nbs??,sg??,mbs??) then print "Resize Successful."

================================================================================
function openfile(f$)

Opens an existing file and returns a handle to the file allowing
subsequent access by the other DOS file commands.  If file does
not already exist, use MAKEFILE instead.  PBASMLIB always opens
the file for read/write access, so you can do either or both.

f$: Set to path\filename of file to open
openfile: Returns handle to the file, or 0 if an error
          occurred (such as file does not exist).

Example: handle% = openfile(f$) 'handle% is the handle to the file
         if handle%=0 then stop 'Error opening

================================================================================
sub prnout(a$)

Sends a character to the first list device (PRN or LPT1),
unless redirected with the DOS MODE command.  If printer is
busy or offline, keyboard may lock (usually temporarily).

a$: Set to single character to send to printer.  If string
    is longer than one character, only the first character
    will be sent to the printer.

Example: prnout "X"

================================================================================
function pspseg

Returns the segment address of the Program Segment Prefix
(PSP) for the currently executing program.  Executing this
function in the PB IDE will return the PSP address for PB.EXE.
The PSP can be accessed to find out information about the
program that's currently executing, including path\filename.

pspseg: Returns segment of PSP.

Example: def seg = pspseg

================================================================================
sub readfile(h%,numbytes??,sg??,ofs??,nbr??)

Reads data from a file, given a valid file handle from MAKEFILE
or OPENFILE, or from using PB's FILEATTR(FILENUM,2) command.

h%: Set to handle retrieved with MAKEFILE, OPENFILE, or FILEATTR
    if the file was opened by PB.
numbytes??: Set to number of bytes to read from the file (1-65535)
sg??: Set to segment of buffer area to hold file data
ofs??: Set to offset of buffer area to hold file data
nbr??: Returns number of bytes read (0 if none or error)

Example: s$=space$(64) 'Reserve 64 bytes in a string
         readfile h%,64,strseg(s$),strptr(s$),nb?? 'Read 64 bytes into s$
         print nb??;" bytes read from file."

================================================================================
sub readsectors(d%,ns%,ss%,sg??,ofs??,e1%,e2%)

Allows reading of specific logical disk sectors into
memory.  Logical sector numbers are obtained by numbering
each disk sector sequentially from track 0, head 0, sector
1, and continuing until the last sector on the disk is counted.
See WRITESECTORS.

d%: Set to drive to read from (0=A, 1=B, 2=C...)
ns%: Set to number of sectors to read
ss%: Set to starting sector number
sg??: Set to segment value of buffer to hold sector data
ofs??: Set to offset value of buffer to hold sector data
e1%: Returns the following error codes:
     0 = OK (Use this to check for errors)
     1 = bad command                2 = bad address mark
     4 = requested sector not found    8 = DMA failure
    16 = Data CRC error                32 = controller failed
    64 = seek operation failed         128 = attachment failed to respond
e2%: Returns the following error codes:
     0 = write protect error        1 = unknown unit
     2 = drive not ready             3 = unknown command
     4 = data CRC error            5 = bad request structure length
     6 = seek error                 7 = unknown media type
     8 = sector not found        9 = printer out of paper
    10 = write fault             11 = read fault
    12 = general failure           15 = invalid disk change

Example: readsectors 0,5,1,sg??,ofs??,e1%,e2%
         if e1%=0 the print "Read OK."

================================================================================
sub redirect(h1%,h2%)

Allows you to refer a handle to the same device or file
as another handle, thus redirecting that handle.

h1%: Set to handle to be redirected to (file or device)
h2%: Set to handle to redirect

Example: redirect h1%,h2%  'Redirects handle h2% to handle h1%

================================================================================
sub removedir(p$,er%)

Removes a directory using the specified path and drive.  Same
as PB's RMDIR command, but returns an error code instead of
making you trap errors with the ON ERROR command.

p$: Set to drive\path to delete
er%: Returns error code, or 0 if ok.

Example: removedir p$,er% 'er%=0 if directory removed

================================================================================
sub setattrib(f$,attr%,er%)

Sets the attributes of a file.  Similar to PB's ATTRIB command,
but does not require the use of ON ERROR to trap errors.
(See FILEATTRIB) for attribute list

f$: Set to filename to change attribute
attr%: Set to new attribute for file
er%: Returns 0 if ok (attribute set) or error code if error

Example: setattrib f$,attr%,er% 'er%=0 if attribute set successfully

================================================================================
sub setbreak(b%)

Sets or clears the system break flag, which influences CTRL-C
checking when a DOS function is in progress.  When BREAK=ON,
they keyboard is examined for a CTRL-C whenever any I/O is
requested ; when off, it's examined only when executing the
character I/O functions.

b%: Set to 0 to set BREAK=OFF, or 1 to set BREAK=ON

Example: setbreak 1

================================================================================
sub setcmosdate(cn%,yr%,mo%,dy%)

Sets the CMOS time date's chip clock to a
specific date.  Differs from SETDATE in that
only the CMOS chip date setting is affected, not
the system date.  In many versions of DOS, using
SETDATE will affect both the DOS date and the CMOS
date.

cn%: Set to century (19 or 20)
yr%: Set to year (00-99)
mo%: Set to month (1-12)
dy%: Set to day (1-31)

Example: setcmosdate cn%,yr%,mo%,dy%

================================================================================
sub setcmostime(hr%,mn%,sc%,dst%)

Sets the CMOS time/date's chip clock.
This function differs from SETTIME only
in that it sets the CMOS chip time only, and
does not affect the DOS clock.  In many versions
of DOS, setting the DOS clock will also set the
CMOS clock.

hr%: Set to hour (0-23)
mn%: Set to minute (0-59)
sc%: Set to second (0-59)
dst%: Set to 0 if standard time, 1 if daylight savings time

Example: setcmostime 0,0,0,0 'Set clock to midnight standard time

================================================================================
sub setdate(yr%,mo%,dy%)

Sets the system date using a DOS call.  If date is invalid,
old setting will not be changed. (see GETDATE)

yr%: Set to year (1980-2099)
mo%: Set to month (1-12)
dy%: Set to day (1-31)

Example: setdate 1993,11,28 'The day this routine was written

================================================================================
sub setdatime(h%,yr%,mo%,dy%,hr%,mn%,sc%)

Sets the date and time directory settings for a
file.  File must be opened first using OPENFILE or
one of the PB open commands.  See GETDATIME.

h%:  Set to handle of previously opened file
yr%: Set to year of file (1980-2099)
mo%: Set to month of file (1-12)
dy%: Set to day of file (1-31)
hr%: Set to hour of file (0-23)
mn%: Set to minutes of file (0-59)
sc%: Set to seconds of file (0-59)

Example: open "i",#1,"filename" 'Open file
         h% = fileattr(1,2) 'Get DOS file handle
         getdatime h%,yr%,mo%,dy%,hr%,mn%,sc% 'Get file date/time data
         dy%=dy%+1 'Add one to the date (day)
         setdatime h%,yr%,mo%,dy%,hr%,mn%,sc% 'Set file date/time data

================================================================================
function setdrive (d%)

Selects the specified drive to be the current drive
and returns the total number of logical drives in the
system.

d%: Set to disk to select (0=A, 1=B, 2=C etc).
setdrive: Returns total logical drives in system.  Always
         equals 5, or the value of the LASTDRIVE statement
         in CONFIG.SYS, whichever is greater.

Example: a%=setdrive(0) 'a% = total number of logical drives
Example: setdrive 0  'Set drive and discard return value

================================================================================
sub setdta(sg??,ofs??)

Specifies the address of the disk transfer area (DTA), which
is used for some DOS disk-related functions, including the
directory search functions.  If this routine is never called,
the DTA defaults to a 128-byte buffer at offset 80h in the
Program Segment Prefix

sg??:  Set to segment of new disk transfer area address
ofs??: Set to offset of new disk transfer area address

Example: setdta strseg(s$),strptr(s$) 'Set s$ to DTA area

================================================================================
sub setfilepointer(handle%,p&)

Sets the file location pointer relative to the start
of the file.  Similar to PB's SEEK command.

handle%: Set to handle returned by a previous call to
OPENFILE or MAKEFILE.
p&: Set to file pointer value (absolute offset from start of file).
    Start of file is always 0 with this command.

Example: setfilepointer h%,5 'Go to byte #5

================================================================================
sub sethandlecount(nhd%,er%)

Sets the maximum number of files and devices that may be
opened at once using handles by the current process.
Attempts to increase/decrease size of handle table (default
is 20).  It's recommended you use a statement like "d=setmem
(-1000)" first to free some memory for DOS to store more file
handles if you intend to increase the handle count.

nhd%: Set to number of handles desired
er%:  Returns 0 if function successful, or error code if not

Example: sethandlecount 25,er%
         if er%=0 then print "25 handles set."

================================================================================
sub setmalloc(m%)

Sets the code indicating the current MS-DOS strategy for
allocating free memory blocks (see MALLOCSTRAT and MALLOC).
Use MALLOCSTRAT afterward to verify that new allocation strategy
was indeed set by MS-DOS.

m%: Set to allocation strategy desired (see MALLOCSTRAT for
    explanation of values.

Example: setmalloc 1

================================================================================
sub setswitchchar(ch%)

Allows setting of the DOS switch character, used for
command line switches.  Use GETSWITCHCHAR to retrieve
the current DOS switch character.

ch%: Set to ASCII value of new DOS switch character.

Example: setswitchchar asc("#") 'Change it to "#"

================================================================================
sub settime(hr%,mn%,sc%)

Sets the system realtime clock (DOS clock).
(See GETTIME)

hr%: Set to hours (0-23)
mn%: Set to minutes (0-59)
sc%: Set to seconds (0-59)

Example: settime hr%,mn%,sc%

================================================================================
sub setvector(i%,sg??,ofs??)

Sets a machine interrupt vector to point to an interrupt
handling routine.

i%: Set to interrupt number to change (0-255)
sg??: Set to segment of interrupt handler
ofs??: Set to offset of interrupt handler

Example: setvector i%,sg??,o??

================================================================================
sub setverify(vf%)

Sets the dos read-after-write (verify) flag on or off.
The default setting is off.  See VERIFYFLAG function.
VERIFY mode results in slower, but more reliable, disk
transfers.

vf%: Set to 1 to turn VERIFY on, or 0 to turn VERIFY off.

Example: setverify 1  'Set verify flag on

================================================================================
sub spoolcancel(er%)

Cancels all files in the PRINT.COM print queue.
See SPOOLSUBMIT for more details.  Make sure PRINT.COM
is loaded first with ISSPOOLER before calling.

er%: Returns error code, or 0 if ok.

Example: call spoolcancel(er%)

================================================================================
sub spoolhold(er%)

Puts all print jobs in the PRINT.COM queue on hold until
released with SPOOLRELEASE.  See SPOOLSUBMIT for more details.

er%: Returns 0 if ok, or error code if error

Example: call spoolhold(er%)
         if er%=0 then print "Printing on hold."

================================================================================
sub spoolrelease(er%)

Releases the hold put on print jobs in the PRINT.COM
queue with SPOOLHOLD.  See SPOOLHOLD and SPOOLSUBMIT
for further details.

er%: Returns 0 if ok, or error code if error

Example: call spoolrelease(er%)
         if er%=0 then print "Print Hold Released"

================================================================================
sub spoolremove(f$,er%)

Removes a file from the PRINT.COM print queue.  See
SPOOLSUBMIT for more information.

f$: Set to path\filename of file to remove from print queue
er%: Returns 0 if ok, or error code if error.

Example: spoolremove f$,er%
         if er%<>0 then print "Error removing ";f$

================================================================================
sub spoolsubmit(f$,er%)

Submits a file for printing to the PRINT.COM DOS TSR
program.  Check if PRINT.COM is loaded first with ISSPOOLER
before using this command.  Note: The print spooler does not
seem to work within PB's IDE, and can only be used in a standalone
.EXE file.

f$: Set to full path\filename of file to submit for printing.
    (CAN include wildcard characters).
er%: Returns 0 if successful (file submitted), or error
     code if unsuccessful (file not submitted for printing).

Example: spoolsubmit fi$,er%
         print doserr$(er%) 'Prints "OK" if file submitted.

================================================================================
function thispath$

Returns the path of the program currently executing, letting
you determine where it's data files are stored.  See THISPROGRAM$.

thispath$: Returns path of current program with trailing backslash

Example: print thispath$

================================================================================
function thisprogram$

Returns the full path and filename of the
currently executing program (will return PB.EXE
when in the PowerBASIC IDE).

thisprogram$: Returns path\programname

Example: print thisprogram$

================================================================================
function timecode(hr%,mn%,sc%)

Translates a given time (hour, minutes, seconds)
into a word-length coded format DOS uses to store
file times on a disk drive.  Can also be used to
translate a time to a packed format for storage elsewhere.
Odd-numbered seconds values will lose accuracy due to translation
to 2-second interval format by the encoding routine.

hr%: Set to hour (0-23)
mn%: Set to minutes (0-59)
sc%: Set to seconds (0-59)

Example: print timecode(15,32,11)

================================================================================
function verifyflag

Returns the status of the DOS read-after-write (verify)
flag.  See SETVERIFY.

verifyflag: Returns 1 if verify on or 0 if off.

Example: print verifyflag

================================================================================
sub writefile(h%,numbytes??,sg??,ofs??,nbw??)

Writes data to a file, given a valid file handle from MAKEFILE
or OPENFILE, or from using PB's FILEATTR(FILENUM,2) command.

h%: Set to handle retrieved with MAKEFILE, OPENFILE, or FILEATTR
    if the file was opened by PB.
numbytes??: Set to number of bytes to write to the file (1-65535)
sg??: Set to segment of buffer area holding data to write
ofs??: Set to offset of buffer area holding data to write
nbw??: Returns number of bytes written (0 if none or error)

Example: writefile h%,len(s$),strseg(s$),strptr(s$),nb?? 'write contents of s$ to file h%
         print nb??;" bytes written to file."

================================================================================
sub writesectors(d%,ns%,ss%,sg??,ofs??,e1%,e2%)

Allows writing of specific logical disk sectors from memory.
Logical sector numbers are obtained by numbering
each disk sector sequentially from track 0, head 0, sector
1, and continuing until the last sector on the disk is counted.
See READSECTORS.  Caution: This routine can damage disk data!

d%: Set to drive to write to (0=A, 1=B, 2=C...)
ns%: Set to number of sectors to write
ss%: Set to starting sector number
sg??: Set to segment value of buffer holding sector data
ofs??: Set to offset value of buffer holding sector data
e1%: Returns the following error codes:
     0 = OK (Use this to check for errors)
     1 = bad command                2 = bad address mark
     4 = requested sector not found     8 = DMA failure
    16 = Data CRC error                 32 = controller failed
    64 = seek operation failed          128 = attachment failed to respond
e2%: Returns the following error codes:
     0 = write protect error        1 = unknown unit
     2 = drive not ready             3 = unknown command
     4 = data CRC error            5 = bad request structure length
     6 = seek error                 7 = unknown media type
     8 = sector not found        9 = printer out of paper
    10 = write fault             11 = read fault
    12 = general failure           15 = invalid disk change

Example: writesectors 0,5,1,sg??,ofs??,e1%,e2%
         if e1%=0 the print "Write OK."