/*
 * $Id: ftisprn.txt 15102 2010-07-14 12:48:39Z vszakats $
 */

/*  $DOC$
 *  $FUNCNAME$
 *     FT_ISPRINT()
 *  $CATEGORY$
 *     DOS/BIOS
 *  $ONELINER$
 *     Check printer status
 *  $SYNTAX$
 *     FT_ISPRINT( [ <cDevice> ] ) -> lResult
 *  $ARGUMENTS$
 *     <cDevice> is optional and is the device to test (LPT2, COM1, etc.).
 *     If omitted, the function will default to the PRN device.
 *  $RETURNS$
 *     .T.  if device is ready for output.
 *     .F.  if one of the following conditions occurs:
 *          1)  The device is not ready.
 *          2)  The device does not exist.
 *          3)  DOS couldn't open the device for some reason
 *              (such as no file handles available).
 *  $DESCRIPTION$
 *     The Clipper IsPrinter() function is somewhat limited because it only
 *     works with LPT1.  Furthermore, it talks directly to the hardware, so
 *     if you have redirected LPT1 via the DOS MODE command, the IsPrinter()
 *     function will return erroneous results.
 * 
 *     This function offers a better alternative.  Instead of talking to the
 *     hardware, it issues a DOS call that checks to see if the device is
 *     ready or not.  That gives DOS an opportunity to deal with any
 *     redirections, and since you pass the device name as a parameter, you
 *     can test any device, not just LPT1 (note that the function defaults
 *     to PRN if you fail to pass a valid parameter).
 * 
 *     The function also temporarily traps the DOS critical error handler so
 *     you don't get any nasty error messages if the device isn't ready.  It
 *     restores the old critical error handler before exiting.
 * 
 *     Note that although this function is mainly designed for testing
 *     printers, you can also check to see if a drive is ready.  Since DOS
 *     thinks the NUL device exists on every drive, you can pass a drive
 *     letter followed by NUL as a parameter.  If DOS is able to open the
 *     NUL device, then the drive is ready, otherwise the door is open or
 *     something else is wrong.
 * 
 *     The source code is written to adhere to Turbo Assembler's IDEAL mode.
 *     To use another assembler, you will need to rearrange the PROC and
 *     SEGMENT directives, and also the ENDP and ENDS directives (a very
 *     minor task).
 *  $EXAMPLES$
 *     IF ! FT_ISPRINT()
 *        Qout( "PRN is not ready!" )
 *     ENDIF
 * 
 *     IF ! FT_ISPRINT( "COM2" )
 *        Qout( "Check the device on COM2.  Something is wrong." )
 *     ENDIF
 * 
 *     IF ! FT_ISPRINT( "A:\nul" )
 *        Qout( "Oops, better check drive A!" )
 *     ENDIF
 *  $END$
 */
