   The following is, to all intents and purposes, a direct lift from
the HP LaserJet series II Printer Technical Reference Manual.


   A typical printer task requires the use of several commands. 
Applications may perform the same task numerous times.  For tasks
performed repeatedly, PCL provides macro functionality to reduce the
number of commands that must be sent to the printer.  A macro is a
collection of escape sequences, control codes, and data, downloaded
to the printer, whose execution can be initiated using a single
command.

   A unique identification (ID) number should be designated prior to
the definition of a macro; this number is then associated with the
macro.  If a macro is already associated with this ID number, the
existing macro will be deleted from user memory during the definition
of the new macro.  Subsequent macro operations are accomplished using
the macro ID number.

   A macro is created in several steps.  First, a command is sent to
the printer that indicates the start of a macro definition.  Next,
the escape sequences, control codes, and data that constitute the
macro are sent to the printer in the intended order of their
execution.  Finally, a command is sent to the printer that indiciates
the end of the macro definition.

   Macros occupy a portion of user memory.  Depending on the amount of
available user memory, up to 32 macros can be stored in memory
simultaneously.  [This will also depend on how much memory has been
used up by downloaded fonts, or other memory-eating conveniences.]

Macro Invocation:
   There are three ways to invoke a macro:  Execute, Call, and Overlay.

   When a macro is >executed<, it begins performing its commands using
the current modified print environment.  Changes made to feature
settings during macro execution are recorded in the modified print
environment;  these changes are retained upon completion of the macro
execution.

   When a macro is >called<, it begins performing its commands using
the current modified print environment.  Changes made to feature
settings during a macro call are recorded in the modified print
environment;  however, these changes are not retained upon completion
of the macro call.  The modified print environment that existed prior
to the macro call is restored.

   When a macro is enabled for automatic >overlay<, its execution will
be the final operation each time a page is printed.  Before the macro
is executed, the current modified print environment is saved and
replaced with the overlay environment.  The overlay environment is a
combination of the user default and the current modified print
environments.  Changes made to feature settings during macro overlay
are recorded in the modified print environment;  however, these
changes are not retained upon completion of the macro overlay.  The
modified print environment that existed prior to the macro overlay is
restored.

   The overlay environment consists of the current settings for the
following features with the remainder of the environmental features
set to their user default values:

      page length          paper source
      page size            number of copies
      orientation          cursor position stack

NOTE:    The current cursor position is not part of the modified print
environment;  therefore, the cursor position is not saved when a
macro is called, nor is it restored upon completion.  The push/pop
cursor position command can be used to save and recall a cursor
position.


Temporary/Permanent macros:
   During its definition, a macro is automatically designated as
temporary.  A temporary macro is one that is deleted from user memory
during a printer reset.  A macro can be designated as permanent to
prevent the printer from deleting it during a printer reset.  A macro
is designated as temporary or permanent by reference to its ID
number.

Deleting macros:
   There are several mechanisms provided by PCL macro control for
explicit deletion of macros from user memory.  These include commands
to delete all macros, all temporary macros, or an individual macro by
reference to its macro ID number.  [Needless to say, turning off the
printer deletes everything, including macros.]


[For the following section, <esc> means the escape character, ascii 27.]

MACRO ID:
   The macro ID command specifies an ID number for use in subsequent
macro commands.

      <esc>&f#Y

   Where # = the macro ID number assigned (0 to 32767).  The factory default
macro ID is zero.

   Example:    To establish a macro ID number of 5, send:

               <esc>&f5Y

               This number (5) will be used in subsequent macro operations.

MACRO CONTROL:
   The macro control command provides mechanisms for definition,
invocation, and deletion of macros.

      <esc>&f#X

   Where # =   0  Start macro definition (last ID specified)
               1  Stop macro definition
               2  Execute macro (last ID specified)
               3  Call macro (last ID specified)
               4  Enable macro for automatic overlay (last ID specified)
               5  Disable automatic overlay
               6  Delete all macros
               7  Delete all temporary macros
               8  Delete macro (last ID specified)
               9  Make macro temporary (last ID specified)
               10 Make macro permanent (last ID specified)

NOTE: 1. A macro may call or execute another macro which in turn may call or
         execute another macro; two levels of nesting are allowed.

      2. Other than call and execute, no macro control operations may occur
         within a macro.

      3. A printer reset command is not allowed in a macro.

      4. No font management commands are allowed in a macro, that is, fonts
         may not be downloaded, deleted or made permanent in a macro.

   Example:    To define a macro with an ID of 7, send:
               
               <esc>&f7y0X
                  .
                  .
                  .
            escape sequences, control codes, and data
                  .
                  .
                  .
               <esc>&f1X


               To make the macro with an ID of 7 permanent, send:

               <esc>&f7y10X

               To enable the macro with an ID of 7 for automatic overlay, send:

               <esc>&f7y4X

               To delete the macro with an ID of 7, send:

               <esc>&f7y8X


MACRO CONTROL EXAMPLE:
   The following illustrates the definition of a letterhead macro.

   <esc>&f1Y                        Specify the macro ID as one
   <esc>&f0x                        Start macro definition                                 
   <esc>&A540h360V                  Position logo at (540, 360) decipoints
                                     in the PCL coordinate system
   <esc>*t150R                      Set graphics resolution to 150
                                     dots-per-inch
   <esc>*r1A                        Start raster image of logo
   <esc>*b60W [Raster data]         Send the first raster line
      .
      .
      .
   <esc>*b60W [Raster data]         Send the last raster line
   <esc>*rB                         Stop raster graphics
   <esc>&a540h780V                  Position for lettering at (540, 780)
                                     decipoints
   <esc>(1X                         Select font 1

   ABC Corp.                        Text
   Post Office Box 15               Text
   Fred, Texas  83707               Text

   <esc>&a540h960V                  Position first rule at (540, 960)
                                     decipoints
   <esc>*c10v4680H                  Set rule height and width
   <esc>*c0P                        Print the first rule
   <esc>&a540h980V                  Position second rule at (540, 980)
                                     decipoints
   <esc>*c0P                        Print second rule
   <esc>&a540h1200V                 Position first line of text at
                                     (540, 1200) decipoints
   <esc>&f1X                        Stop macro definition.


   This macro can now be executed, called, or enabled for automatic
   overlay.




CLIPPER USE OF PCL MACRO COMMANDS:

   You've got several ways of submitting any of these commands to the
printer via Clipper.  One is to just go ahead and print them (I
prefer the use of ?? since that way you presumably reduce the
possibility of printing your way past the bottom of the page).  A
second is to put each of the macros you intend to use in text files
and then read them in with FREAD() and send 'em out to the printer
with FWRITE(), or some such mechanism.  Yet another is to use the DOS
COPY command, as in: !COPY FILENAME/B PRN (the /B is necessary, since
you want COPY to treat the file as a binary file).  I've generally
used this as my method of downloading fonts from within Clipper (for
some reason, I couldn't get FREAD() and FWRITE() to work this
particular trick - if anyone has a C udf which mimics DOS's COPY,
without loading a shell and chewing up memory, please let me know).
   Use what you're comfortable with.  Imagine, if you will, a library of
such macros/overlays in a database or library file, selectable from
a popup window controlled by achoice().
