Documentation for TMCLIP.LIB, a Clipper function library

Written by Ted Means, Wichita, Kansas

This software is provided free of charge, and no "registration fees" or
anything of that nature is expected. You may freely copy the software and
share it with others, but please don't charge any money to do it. If I'm not
making any money, you shouldn't either.

I make no promises that these functions will work perfectly. My testing
facilities are limited to two computers (the one at home and the one at work),
so I can't guarantee perfection. However, testing on the two machines to which
I had access was extensive and I encountered no problems. If you find a
function that doesn't work on your machine, drop me a line on CompuServe
[73067,3332]. If I can find out what's wrong, I'll fix it and upload an
upgrade. Even if you encounter no problems, I'd still like to hear comments
and suggestions. Thanks and Happy Clipping!
===============================================================================



I've tested the library with two different linkers--PLINK86 and Microsoft LINK
version 3.65. If you use a different linker, you're on your own.

To use PLINK86, your link step will look something like this:

PLINK86 FI LIB CLIPPER,TMCLIP,EXTEND

You need to include EXTEND because some functions in TMCLIP use EXTEND.


To use Microsoft LINK, your link step will look something like this:

LINK ,,,CLIPPER+EXTEND+TMCLIP


If you're using other libraries besides those listed here, just add them to
the library list. You may need to experiment with the order in which they
are listed to get the results you want.
===============================================================================



Following is a description of each function in the library. You will see the
parameters that are passed to the functions expressed this way:

means that a character expression is passed.
means that a numeric expression is passed.

If any invalid parameter is passed, the function will either return an error
code, or simply fail to work. See the individual function descriptions for
further details.



*******************************************************************************
DEFAULT()

Syntax: DEFAULT()

Use: To determine the current default drive.

Arguments: None

Return value of the function: Character
The character returned is the default drive.

Example of usage: DEFDRIVE = DEFAULT()
*******************************************************************************



*******************************************************************************
CHKDRIVE()

Syntax: CHKDRIVE()

Use: To determine the status of a specified disk drive.

Arguments: is the letter of the drive to be checked.

Return value of the function: Numeric
0 means the drive is OK
1 means the disk is write-protected
2 means the drive door is open
3 means the disk is not formatted
4 means a miscellanous error
99 means an invalid parameter was passed

Example of usage: DRVSTATUS = CHKDRIVE("B") && Check drive B

Tip: Use this function avoid error conditions that arise because the drive is
not ready. You can trap the error and have the user take corrective
action.
*******************************************************************************



*******************************************************************************
FLOPPIES()

Syntax: FLOPPIES()

Use: To determine the number of floppy disk drives, and if there is only
one, determine whether DOS is using it as drive A or drive B.

Arguments: None

Return value of the function: Character
"A" means there is one floppy drive, and DOS
is using it as drive A.
"B" means there is one floppy drive, and DOS
is using it as drive B.
"2" means there are two floppy drives.

Example of usage: FLOPSTATUS = FLOPPIES()

Tip: On systems with only one floppy disk drive, DOS can access that drive as
either A or B, but not both at the same time. If you try to access it as
drive B when DOS thinks it's drive A, you'll get a message that says
"Insert diskette for drive B and strike a key when ready" regardless of
the fact that you just painted a nice-looking data entry screen. This
function helps you avoid that problem by reporting if there is only one
floppy drive, and if so, whether it's currently drive A or B. From there
it's simply a matter of putting the correct drive in your file spec
before you open the file.
*******************************************************************************



*******************************************************************************
FORCEA()

Use: To force a single floppy system into a state where the single floppy is
treated by DOS as drive A.

Syntax: FORCEA()

Arguments: None

Return value of the function: Meaningless

Example of usage: IF FLOPPIES() <> "2"
FORCEA()
ENDIF

Tip: If by using the FLOPPIES() function you determine that there is only one
floppy drive on the machine, this function can be used to force DOS to
treat it as drive A. Useful for avoiding the message described in the
previous function.
*******************************************************************************



*******************************************************************************
KEYIN()

Syntax: KEYIN()

Use: To obtain a single keystroke and report the key pressed.

Arguments: None

Return value of the function: Numeric
The return value may have up to six digits.
The least significant three digits are the
ASCII value of the key pressed; the most
significant three digits are the BIOS scan
code. Refer to a scan code table if you need
to determine which codes refer to which keys.

Example of usage: KEYHIT = KEYIN()
ASCVALUE = MOD(KEYHIT, 1000)
SCANCODE = INT(KEYHIT / 1000)

Tip: This function is similar to INKEY(), but returns the ASCII value and the
scan code. This can be useful for detecting unusual key combinations.
Note that since two values are returned in one number, you have to divide
by 1000 to split it up. See the above example.
*******************************************************************************



*******************************************************************************
ENHKEYIN()

Syntax: ENHKEYIN()

Use: To obtain a single keystroke and report the key pressed. Same as the
above function, except it recognizes the enhanced keyboard.

Arguments: None

Return value of the function: Numeric
See the previous function for a description.

Example of usage: See the previous function.

Tip: This function is identical to KEYIN(), except it will recognize the
enhanced keyboard. Therefore, keys such as F11 and F12 will be acted
on. If this function doesn't work on your machine, it's probably
because you have an older BIOS. Use the previous function instead.
*******************************************************************************



*******************************************************************************
HIGHDISK()

Syntax: HIGHDISK()

Use: To determine the last disk drive letter on the computer.

Arguments: None

Return value of the function: Character
The character returned is the last available
disk drive.

Example of usage: LASTDRV = HIGHDISK()

Tip: This function returns the last available drive, regardless of the
LASTDRIVE setting in the CONFIG.SYS file. This can be useful to trap
errors if the user specifies an invalid disk drive.
*******************************************************************************



*******************************************************************************
EXSUB()

Syntax: EXSUB(,
Use: To determine if the specifed subdirectory exists on the specified
disk drive.

Arguments: is the disk drive letter. is the subdirectory
to be checked. Do **NOT** use a backslash as the first character
of the subdirectory name.

Return value of the function: Logical
.T. means the subdirectory exists
.F. means the subdirectory does not exist, or
invalid parameters were passed

Example of usage: IF .NOT. EXSUB("C", "DATA\TAXES")
? "That directory does not exist!"
ENDIF

Tip: Use this function to make sure the user did not specify an invalid
subdirectory.
*******************************************************************************



*******************************************************************************
MKSUB()

Syntax: MKSUB()

Use: To create a subdirectory

Arguments: is a path specification which can include a drive letter.

Return value of the function: Numeric
0 indicates the subdirectory was created
1 indicates the disk was full
3 indicates path not found
5 indicates the subdirectory already existed
or the root directory was full
99 indicates an invalid parameter was passed

Example of usage: ERRSTATUS = MKSUB("C:\CLIPPER")
*******************************************************************************



*******************************************************************************
BIOSDATE()

Syntax: BIOSDATE()

Use: To determine the BIOS release date.

Arguments: None

Return value of the function: Date

Example of usage: BDATE = BIOSDATE()

Tip: If your program makes use of BIOS functions only available in later
versions of the ROM BIOS, you can use this function to make sure they
will be supported on the machine running the program.
*******************************************************************************



*******************************************************************************
KEYWAIT()

Syntax: KEYWAIT()

Use: To pause execution until any key is pressed.

Arguments: None

Return value of the function: Meaningless

Example of usage: ? "Press any key when ready."
KEYWAIT()

Tip: This function is very similar to the WAIT statement, with two exceptions.
No message is displayed on the screen, and non-character keys, such as
Shift, Alt, and Ctrl, are detected. That way, "Press any key" really
means what it says.
*******************************************************************************



*******************************************************************************
ENHKEYWAIT()

Syntax: ENHKEYWAIT()

Use: To pause execution until any key is pressed. Same as the previous
function, except that the enhanced keyboard is recognized.

Arguments: None

Return value of the function: Meaningless

Example of usage: See previous function.

Tip: Same as previous function, except that it recognizes the enhanced
keyboard, so keys such as F11 and F12 are detected. If this function
doesn't work on your computer, it's probably because you have an older
version of the ROM BIOS. Use the previous function instead.
*******************************************************************************



*******************************************************************************
STUFFKEY()

Use: To stuff a keystroke into the keyboard buffer.

Syntax: STUFFKEY()

Arguments: is the Clipper INKEY() value of the key to be stuffed.

Return value of the function: Logical
.T. means the keystroke was put in the buffer
.F. means the buffer was full or an invalid
INKEY() value was passed as a parameter

Example of usage: STUFFKEY(28)

Tip: This is similar to the KEYBOARD statement, with two major exceptions.
Since an INKEY() value is passed as a parameter, ANY keystroke recognized
by Clipper can be stuffed into the keyboard buffer. This includes
function keys and other special keys. However, since a number is passed
as a parameter instead of a character string, only one character can be
inserted at a time.
*******************************************************************************



*******************************************************************************
BEEP()

Use: To sound the system speaker.

Syntax: BEEP()

Arguments: is the number of times to sound the speaker. If is
not supplied, the default is one.

Return value of the function: Numeric
The value returned is the number of times the
speaker was sounded.

Example of usage: BEEP(3)

Tip: Useful for sounding the speaker more than once, as in error conditions.
*******************************************************************************