PRTLIB DOCUMENTATION


Overview
========
PRTCODES ver. 1.1 is a Clipper 5.01 function suite that consists of eight
callable functions.  These functions allow you to easily send printer control
codes, select different printers, maintain printer definitions 
(add/edit/delete), and test printer definitions.  These printer definitions are
contained in records of a printer definition database.  It is written in 100%
Clipper 5.01 code and uses no PUBLIC or PRIVATE variables.  PRTCODES is
network ready and supports a multi-user environment.

The maintenance procedure allows the user to enter printer setup strings in
familiar Lotus style format (i.e. \027E).

This version supports 30 different printer codes.  These codes are stored in a
static array and are easily referenced by #xtranslates supplied in the include
file PCODES.CH.  The printer features supported and #xtranslates are as follows:

PAT_RESET      =>1
  Reset printer at the end of print job
PAT_INIT       =>2
  Initialize printer before starting print job
PAT_UON        =>3
  Turn underlining on
PAT_UOFF       =>4
  Turn underlining off
PAT_BON        =>5
  Turn bold on
PAT_BOFF       =>6
  Turn bold off
PAT_ION        =>7
  Turn italics on
PAT_IOFF       =>8
  Turn italics off
PAT_CPI10      =>9
  Set 10 Characters per inch
PAT_CPI12      =>10
  Set 12 Characters per inch
PAT_6LPI       =>11
  Set line spacing to 6 lines per inch
PAT_8LPI       =>12
  Set line spacing to 8 lines per inch
PAT_SHDON      =>13
  Turn shading on
PAT_SHDOFF     =>14
  Turn shading off
PAT_PORT       =>15
  Set page to portrait orientation
PAT_LAND       =>16
  Set page to landscape orientation
PAT_CON        =>17
  Turn compressed print on
PAT_COFF       =>18
  Turn compressed print off
PAT_DRAFT      =>19
  Set Draft mode
PAT_LQ         =>20
  Set Letter Quality mode
PAT_WIDEON     =>21
  Turn double wide print on
PAT_WIDEOFF    =>22
  Turn double wide print off
PAT_REVON      =>23
  Turn reverse print on
PAT_REVOFF     =>24
  Turn reverse print off
PAT_DBLHION    =>25
  Turn double high print on
PAT_DBLHIOFF   =>26
  Turn double wide print off
 PAT_DWDHON    =>27
   Turn double wide/high print on
 PAT_DWDHOFF   =>28
   Turn double wide/high print off
 PAT_FL12      =>29
   Set form length to 12 inches
 PAT_FL11      =>30
   Set form length to 11 inches

Files
=====
The following files are part of this ZIP file:

readme.txt         this file
compile.bat        Batch file to compile demo program
pat.prg            Main menu for demo program, shows initialization
rpt.prg            Sample report function, shows usage of printer codes
pat_defs.dbf       Database of printer definitions
pat_defs.ntx       Index by ID for printer definition database
pcodes.ch          header file for printer code array subscripts
prtcodes.obj       object code containing printer library function suite


Functions
=========
There are eight callable functions contained in PRTCODES.OBJ:
   InitPAT()
   SelPrntr()
   DefPrntr()
   PrintCodes()
   GetCodes()
   MakePat()
   TestPat()
   SetUserPort()

 INITPAT()
Initialize PAT system


Syntax

    INITPAT(<cDefPrinter>, <cFileSpec>, [<acAllowPrntrs>]) --> lRetVal

Arguments

    <cDefPrinter> is the printer ID for the default printer to load

    <cFileSpec> is the full file specification for the printer
    definition database

    <acAllowPrntrs> is a optional two dimensional array that contains
    the printers that are allowed to be selected by SELPRNTR()

    Each element in this array is itself a two element array where the
    first element of the subarray contains the printer ID and the second
    element contains the associated printer port used for redirection.

Returns

    INITPAT() returns .T. if successful, .F. otherwise

Description

    INITPAT() is used to initialize the PAT system.  All internal STATIC
    variables are set and the default printer escape codes are loaded.

    
      Note

    INITPAT() is intended to be called once during the application startup.
    

Example

    The following example demonstrate INITPAT() in action:

    acPrinterDefs := { { "LASERJET", "LPT1" }, ;
                       { "EPSON",    "LPT2" }, ;
                       { "STANDARD", "DUMP.PRN" } }
    If !InitPAT("LASERJET", "PAT_DEFS", acPrinterDefs)
       ? "Unable to initialize PAT system, press any key to continue"
       Inkey(0)
    Endif


 SELPRNTR()
Select a printer and load its printer codes


Syntax

    SELPRNTR() --> lOK

Returns

    SELPRNTR() returns .T. if user made selection, .F. otherwise.

Description

    SELPRNTR() allows the user to change the active printer.

Example

    The following example demonstrates SELPRNTR() in action:

    acPrinterDefs := { { "LASERJET", "LPT1" }, ;
                       { "EPSON",    "LPT2" }, ;
                       { "STANDARD", "DUMP.PRN" } }
    If SelPrntr()
       SetUserPort(DefPrntr(), acPrinterDefs)
    Endif


 DEFPRNTR()
Return character string ID of default printer selected


Syntax

    DEFPRNTR() --> cPrinterID

Returns

    DEFPRNTR() returns the ID of the default printer

Description

    DEFPRNTR() is provided to simply return the current printer ID
    from the STATIC variable contained withing PRTCODES.PRG

Example

    The following example demonstrate DEFPRNTR() in action:

         If SelPrntr()
            SetUserPort(DefPrntr(), acPrinterDefs)
         Endif


 PRINTCODES()
Outputs specified printer code(s) to printer


Syntax

    PRINTCODES(<nSubscript> | <anSubscripts> ) --> NIL

Arguments

    <nSubscript> is the array subscript for the code desired

    <anSubscript> is an array of subscripts for the code desired

Returns

    PRINTCODES() returns NIL

Description

    PRINTCODES() is useful for sending printer control code(s) to the current
    print device.  The numeric parameter <nSubscript> is best specified
    using the #xtranslates provided in the include file PCODES.ch.

    You may pass an array <anSubscript> if more than one code needs to be
    sent to avoid multiple calls to PRINTCODES().

    PRINTCODES() saves the current PROW(), PCOL(), _SET_PRINTER and
    _SET_CONSOLE status prior to sending the control codes with the print
    command "?".

Examples

    The following examples demonstrate PRINTCODES() in action:

    PRINTCODES({PAT_INIT, PAT_CON}) // Initialize printer in compressed mode
    Type Error.log to print         // Output text file
    Eject                           // Eject page
    PRINTCODES(PAT_RESET)           // Reset printer to power on state


 GETCODES()
Get a specified printer code


Syntax

    GETCODES(<nSubscript>) --> cPrinterCode

Arguments

    <nSubscript> is the static array subscript of the element desired

Returns

    GETCODES() returns a printer code as a character expression

Description

    GETCODES() is useful for including printer codes as part of a
    character string.  The numeric parameter <nSubscript> is best specified
    using the #xtranslates included in the file PCODES.ch.

Example

    The following example demonstrate GETCODES() in action:

    Set Device to Print
    // The next line sends a printer initialization string
    @ PRow(), 0      Say GetCodes(PAT_INIT) + 'ACME Inc'
    // The next line underlines the word "Date:"
    @ PRow()+1, 0    Say GetCodes(PAT_UON) + 'Date: ' + GetCodes(PAT_UOFF)
    @ PRow(), PCol() Say DtoC(Date())
    // Report body...
    //
    Eject
    // The next line resets the printer to its power on state
    PRINTCODES(PAT_RESET)
    Set Device to Screen


 MAKEPAT()
Printer definition maintenance system


Syntax

    MAKEPAT() --> NIL

Returns

    MAKEPAT() returns NIL

Description

    MAKEPAT() is used to create, edit and delete printer definitions
    from the database.  This procedure is written network aware and handles
    multi-user access.

Example

    The following example demonstrate MAKEPAT() in action:

    MakePat()


 TESTPAT()
Test active printer definition


Syntax

    TESTPAT() --> NIL

Returns

    TESTPAT() returns NIL

Description

    TESTPAT() is used to test the active printer definition

Example

    The following example demonstrate TESTPAT() in action:

    TestPat()


 SETUSERPORT()
Set printer to port associated with default printer


Syntax

    SETUSERPORT(<cPrinterID>, <acPrinterDefs>) --> lRetVal

Arguments

    <cPrinterID> is the printer ID used to scan <acPrinterDefs>

    <acPrinterDefs> is the two dimensional array to find <cPrinterID>

Returns

    SETUSERPORT() returns .T. is successful, .F. otherwise

Description

    SETUSERPORT() redirects Clipper's output using the SET PRINTER TO
    command.  All output sent to the printer will be directed to the
    specified DOS device selected via SELPRNTR().

    <acPrinterDefs> is a two dimensional array where each element in the
    array is itself a two element array where the first element of the
    subarray contains the printer ID and the second element contains the
    associated printer port used for redirection.

    This function has been provided mostly for network users that have
    their various available printers mapped to specific DOS devices.
    The network printer manager typically captures output sent to the
    specified DOS device and re-directs it to the appropriate network
    printer.

    This can also be used to capture output to disk by setting the DOS
    device to a file name.  All output from Clipper will then go to the
    file name specified.

Examples

    The following examples demonstrate a call to SETUSERPORT():

    acPrinterDefs := { { "LASERJET", "LPT1" }, ;
                       { "EPSON",    "LPT2" }, ;
                       { "STANDARD", "DUMP.PRN" } }

       If SelPrntr()
          SetUserPort(DefPrntr(), acPrinterDefs)
       Endif


Registration
============
This function suite is a 100% complete working version contained in the object
file PRTCODES.OBJ.  I am marketing this library as shareware.  This means that
if you use it, I expect that you register it with me.  The registration fee is
$15 US (NY State residents add appropriate sales tax and indicate county).  In
return, you will receive the complete source code (written entirely in
Clipper 5.01).

Once you have registered, you are free to link the printer library functions
into your own .EXEs and distribute them as you please.  You may also modify the
source code as long as you leave the program headers intact and do not resell
the function library as your own.  You may not distribute the source code to any
party under any circumstances without written approval from S&A PC Solutions,
Inc.

Send all requests, registrations and suggestions to:

John Agusta
S&A PC Solutions, Inc.
24 Lena Road
Forestburgh, New York 12777-6206

Phone: (718) 366-6060
FAX:   (718) 366-6184
CIS    71650,2251
