                                     Manual
                                    PrtInfo

                          Created 03-29-2005 T. Milius
                          Changed 01-28-2007 T. Milius

     ----------------------------------------------------------------------

                                    Content

     * Overview
     * Installation
          * Requirements
          * Performing the installation
               * Network
     * Manual
     * License
     * Contact
     * History
          * Version 1.00
          * Version 1.01
          * Version 1.02
          * Version 1.03
          * Version 1.04
          * Version 1.05
          * Version 1.06
          * Version 1.07
          * Version 1.08
     * Future
     * Technical details
          * Directories
               * The cartridge database
          * Actions
               * Colours
               * Cartridges
          * Functions
               * Variables
          * DRAW files
          * Other remarks

                                    Overview

   PrtInfo provides simple actions on printers, like eg cleaning of
   printheads, changing of cartridges etc. and displaying of cartridge ink
   levels. This is done independently of the printing process.

                                  Installation

Requirements

   To install PrtInfo you are needing around 1MB disc space, 300KB RAM and
   RISC OS 3.5 or later. USB printers are only supported if using the Castle
   USB version.

   Printer with parallel interface can be controlled only in a limited way in
   the moment because nor RISC OS neither this program supports Nibble or ECP
   mode.

Performing the installation

   Copy !PrtInfo to an arbitrary position on your harddisc.

   It may be necassary to modify the files
   "<PrtInfo$Dir>.Resources.TypeAlias" and "<PrtInfo$Dir>.Resources.PrtAlias"
   to the requirements of your own printer. In case that printers are not
   determined automatically using USB it is likely that at least "PrtAlias"
   must be adapted because else the program isn't knowing the printer type.
   "PrtAlias" can be modified inside every text editior. Simply add a line to
   the end of the file which starts with the name of your printer. The name
   must be exactly the same like it is shown on the left side on the
   appliaction bar (case sensitive!). After a comma enter the name of the
   manufacturer followed by another comma and the printer type. Take care of
   small and capital letters also. It is important that all spaces in the
   names are replaced by "_".

   You can obtain the names of the manufacturer and the printer type from the
   file names inside the "<PrtInfo$Dir>.Resources.Commands" directory and its
   subdirectories. In the case that manufacturer and printer are not already
   existing you can create your own names. If there is no printer type
   available which resources you can use for controlling your printer you
   must create the according files yourself. A detailed explanation how to do
   so you are finding insid ethe chapter technical details. But in case that
   you are finding a printer type which resources are matching for your
   printer (this may be done by trying through the resources) so you can
   enable this resources for your printer by adding a new line to
   "TypeAlias". At the beginning this line must contain manufacturer and
   printer type written like inside "PrtAlias". Then manufacturer and printer
   type of the printer which resources shall be used must follow. This
   concept can be used also for USB prinetrs which type is determined
   automatically but for which no resources are available.

   You should place entries inside "<PrtInfo$Dir>.Resources.PrtAlias" only in
   such cases if the printer names are RISC OS standard names. If you have
   renamed the printers eg to support various paper qualities you should
   place your entries inside the file "<Choices$Dir>.PrtInfo.PrtAlias". This
   file will not be replaced at program updates instead to
   "<PrtInfo$Dir>.Resources.PrtAlias" and will be evaluated before the later
   one.

  Network

   PrtInfo supports shared printers. Therefore certain operations are passed
   over the network to the PrtInfo on the machine to which the printer is
   connected to. The results are transfered back over the network to the
   calling PrtInfo.

   The most users are running onyl one RISC OS machine and are therefore not
   sharing any printers between several RISC OS machines. Therefore the
   network will be switched off after the installation of PrtInfo. If you
   want to run PrtInfo inside a network of RISC OS machines with shared
   printers you have to change the setiings. The settings are stored inside
   the file "<ChoicesWrite$Dir>.PrtInfo.Settings".

   PrtInfo is using network port 9152 to communicate with its pedants on
   other RISC OS machines. This port can be changed using the parameter
   "Port" uniform for the whole network. To locate problems yout can activate
   a network protocol file by the parameter "NetworkTraceFile". To block
   unwanted accesses from extern there are two parameters called "Network"
   und "Netmask". "Network" additionally determines whether the network is
   activated or not. Each incoming request will be ANDed with "Netmask". The
   result must be equal to the AND-operation of "Network" und "Netmask" else
   the request will berejected. "Network" should contain all relevant numbers
   of the IP of your machine. The relevant Bits are determined by setting the
   according Bits inside "Netmask" to 1. If "Network" has the value 0.0.0.0
   or isn't determined the PrtInfo network activity will be deactivated.

   PrtInfo with network activity will use a small amount of computing power
   (1% on my Iyonix). Without special setup of the network mask there exists
   as on every server without firewall and unlimited access rights the danger
   of external hack attempts in case that you are connecting to the internet.
   Due to some limitations of !Printers PrtInfo will show sometimes a strange
   behaviour if acting as server when a request is started for a shared
   printer for which until then no PrtInfo status windows has been activated
   on the server machine. For a short period it will activate all printers
   provided by !Printers one after the other. At the end the originally
   activated printer will be activated again. tehrefore never use the option
   "Detect Errors" for the printer port if running PrtInfo in network mode.
   In case that tehre is an error on the printer the activation will fail and
   will generate an error box on the server. In case the a connection can't
   be established to another machine PrtInfo will this internally and you
   won't be able to get a status windows for this printer until PrtInfo is
   restarted./P>

                                     Manual

   Start !PrtInfo. On the right side of the program bar the according symbol
   of the program will alert.

   When you are clicking the MENU-key of the mouse above the !PrtInfo symbol
   you will obtain a small menu which allows you to display the copyright and
   this help and also to terminate the program. Additionally you can choose
   whether for each new status window a TRACE protocol file shall be
   generated and display the directory which is containing the generated
   files or the directory which contains your local settings. The TRACE
   protocol files are allowing a detailed problem analysation and are very
   useful during driver development. They are not required under normal
   operation. The files which are containing your local settings are
   explained inside the installation in more details.

   At termination of the program all of its status windows will be closed. In
   worst case if you are just performing a complex action on your printer you
   will leave your printer in an undefinite state. However in most cases this
   will not cause any trouble.

   Choose a printer on the left side of the program bar and press the SELECT
   key of the mouse afterwards above the !PrtInfo symbol.

   If possible a status window for the according printer will open or you
   will get an error message.

   Inside the window title bar the name of the printer to which the window is
   belonging to will be displayed. In case that you are removing the printer
   the according status windows will not be closed automatically. Subsequent
   actions on this printer will lead to error messages.

   At the top of the window you can see three status indicators. Below this
   there is a line for displaying messages. Then a range is following in
   which text and graphics can be displayed depending on the action. Here eg
   you can find explanations for certain actions or the actual level of the
   ink inside the cartridges. The part of the window at the bottom is only
   active in the case that you must do something inside an action. The
   buttons will be filled then with values and sometimes inside the line
   above a short question or explanation will be displayed.

   When you are pressing the MENU mouse button above the status window a menu
   will be shown, which is offering the actions which can be performed on
   your printer and a selection of a cartridge manufacturer. Actions which
   can't be performed on the printer are disabled. In case that you are just
   performing one action all actions are disabled until the actual action is
   finished. Some actions can be performed on various cartridges or print
   heads. Such actions are having a submenus which show the according
   cartridges/heads. Choose an action by clicking on the according menu or
   submenu entry with the SELECT mouse button. The according action will be
   performed afterwards and may change the content of the status windows.

   An exception inside the menu is the entry "cartridge manufacturers".
   Inside its submenu the cartridge manufacturers which are available for
   this printer will be displayed (for the real printer type and not for the
   alias type!). Of course this manufacturers must have been entered inside
   the cartridge database. The manufacturer for which detailed informations
   shall be displayed inside diagrams is marked by a hook and can be changed
   by pressing the SELECT mouse button over another entry. However the
   diagrams won't change their information immediately but first after they
   have been generated again by the according action.

   Some printers allow to perform the cleaning of the heads in several ways.
   You can choose the kind of next cleaning in the submenue of the entry
   "Cleaning Levels" by pressing of the SELECT mouse button above the
   required level.

   During performing an action it may be necassary that certain things must
   be performed manually before the action can be continued or that you must
   do a choice. In such a case the button at the bottom of the status window
   will be activated until you have pressed one of them which will continue
   the action in accordance with your choice.

   Following actions are possible in general:

     * Showing of the cartridge ink level
     * Change of cartridges
     * Clean print heads
     * Showing of the printer status
     * Reset of printer
     * Adjustment of print heads
     * Print a nozzle check
     * Change of print heads
     * Switch off printer

                                   Copyright

   Copyright 2004-2005 by

   Thomas Milius Stade, Germany (Contact)

   The program may be copied free of charge.

   Source of the dumper is open source with some small restrictions to
   prevent commercial use without my agreement. I am allowed to use this code
   inside programs without publishing the code of this programs. These
   programs may be commercial. Other developers can use this source freely
   inside own software if the source code of this programs is made public to
   same conditions like valid to this code and no commercial profit is taken
   from the programs based on this code or must contact myself for my
   agreement of commercial usage. Usage of the source inside programs which
   are under GPL license or something similar is forbidden.

   The manufacturer of the program is taking no responsibility on any damages
   or subsequent damages which are resulting of the usage of the program like
   eg loss of data or damage of the printer. Of course hints on errors are
   always welcome and the manufacturer will try to correct them as soon as
   possible. However a duty for correction does not exists.

                                    History

Version 1.00

   Release date:
     * 03-25-2005

   Price:
     * None because it is open source and freeware

   Remarks:
     * First public version

   Corrected errors:
     * None

   New errors/problems:
     * After switching on EPSON printers may block in conjunction with
       Castles USB-stack.

   New features:
     * Showing of the cartridge ink level
     * Change of cartridges
     * Clean print heads
     * Showing of the printer status
     * Reset of printer
     * Adjustment of print heads
     * Print a nozzle check
     * Change of print heads
     * Simple cartridge database
     * Can be adapted to each printer
     * Dynamic modification of DRAW files
     * Overlay of several DRAW files possible
     * Small task optimized programming language

Version 1.01

   Release date:
     * 09-25-2005

   Remarks:
     * Not published.

   New features:
     * Variables PROTOCOL and INTERFACE introduced
     * TRACE protocol files introduced

Version 1.02

   Release date:
     * 10-03-2005

   Remarks:
     * Not published.

   Corrected errors:
     * Bug in TypeAlias removed

   New errors/problems:
     * 3 bugs inside get function with length determination

   New features:
     * locale PrtAlias insides Choices
     * get function with length determination for Canon printer
     * Canon drivers changed to new get function
     * Messages changed

Version 1.03

   Release date:
     * 10-09-2005

   Remarks:
     * Not published.

   Corrected errors:
     * get with length determination switched from Little to Big Endian.

   New features:
     * Printer determination changed internally. With this a problem inside
       the !Printers variable handling is bypassed.

Version 1.04

   Release date:
     * 10-11-2005

   Remarks:
     * Not published.

   Corrected errors:
     * bug with data shifting inside get with length determination corrected.

Version 1.05

   Release date:
     * 10-12-2005

   Remarks:
     * Not published.
     * Heavy internal restructurations to prepare handling of shared
       printers.

   Corrected errors:
     * bug in get with length determination at stringtermination corrected.

Version 1.06

   Release date:
     * 10-22-2005

   Remarks:
     * Not published.

   Corrected errors:
     * Bug in TypeAlias evaluation corrected which made TypeAlias useless

   New errors/problems:
     * Names of cleaning levels could be better.

   New features:
     * Compatible with !PrintSpool
     * Internal printer reservation
     * Cleaning levels introduced.
     * Option Cleaning Levels introduced.
     * Variable CLEANINGLEVEL introduced.

Version 1.07

   Release date:
     * 11-27-2005

   Corrected errors:
     * Partially other terms used for the cleaning levels
     * Problem with printer determination cured which was due to a faulty SWI
       of RISC OS on Risc PCs.

   New features:
     * Action to switch off the printer
     * Menu entry to show the directory which contains the individual
       settings added.
     * Status indicator "Error" changed to "No Error".
     * Ability to handle shared printers.
     * Individual configuration file containing network options
     * Network protocol file
     * Cursor will change its shape during activity and the menu above the
       according window is disabled.

Version 1.08

   Release date:
     * 01-28-2007

   Corrected errors:
     * None

   New features:
     * Full multitasking network (GetHostByName)

                                    Contact

   If you are having questions, improvements or remarks don't hesitate to
   contact me:
   Thomas Milius
   Tilsiter Strae 2
   21680 Stade
   Germany

   Telephone:
   04141/65005
   Work days from 19:00 until 21:30 and at weekends

   E-mail:
   Thomas-Milius@t-online.de

   Homepage:
   http://www.thomas-milius.homepage.t-online.de/indexE.htm

                                     Future

   No bigger changes or extensions are planed for the program but new
   resources for other printer types will be added continously. On demand
   other head-/cartridge schemes or colours can be added easily.

   Perhaps the Nibble and/or ECP mode protocol may be implemented to allow an
   improved control of the parallel port.

                               Technical details

Directory scheme

   All files which can be changed by the user are located inside the
   "<PrtInfo$Dir>.Resources"-directory. Additionally there is a local version
   of PrtAlias inside the "<ChoicesWrite$Dir>.PrtInfo" directory and the
   settings file which contains the network configuration.

   +------------------------------------------------------------------------+
   |    Name    |   Type    |                  Description                  |
   |------------+-----------+-----------------------------------------------|
   |            |           | Contains the cartridge database and is        |
   | CtrInfo    | Text file | explained inside a separat chapter in more    |
   |            |           | detail.                                       |
   |------------+-----------+-----------------------------------------------|
   |            |           | Contains the relation between RISC OS printer |
   | PrtAlias   | Text file | names and printer type and is explained       |
   |            |           | inside the installation in more detail.       |
   |------------+-----------+-----------------------------------------------|
   |            |           | Contains the relation between a printer type  |
   | TypeAlias  | Text file | and a similar printer type which resources    |
   |            |           | can be used and is explained inside the       |
   |            |           | installation in more detail.                  |
   |------------+-----------+-----------------------------------------------|
   |            |           | Contains the network configuration and is     |
   | Settings   | Text file | explained in more details inside the          |
   |            |           | Installation.                                 |
   |------------+-----------+-----------------------------------------------|
   |            |           | Contains a subdirectory for each printer      |
   | Commands   | Directory | manufacturer in which the command files for   |
   |            |           | the printers are located. This structure is   |
   |            |           | required by the program.                      |
   |------------+-----------+-----------------------------------------------|
   |            |           | Contains a subdirectory for each printer      |
   |            |           | manufacturer in which the DRAW files for      |
   | cartridges | Directory | displaying the actual ink levels of the       |
   |            |           | printer are located. This structure is only a |
   |            |           | recommendation depending on the pathes used   |
   |            |           | inside functions.                             |
   |------------+-----------+-----------------------------------------------|
   |            |           | Contains a subdirectory for each printer      |
   |            |           | manufacturer in which other subdirectories    |
   |            |           | are containing DRAW files for explanation of  |
   |            |           | certain actions on the according printer.     |
   |            |           | Such explanations can be also located on      |
   | Tutorials  | Directory | manufacturer directory level. In the case     |
   |            |           | that the explanations are containing text     |
   |            |           | their file name should end with the number of |
   |            |           | the related territory (exception 1=UK). This  |
   |            |           | structure is only a recommendation depending  |
   |            |           | on the pathes used inside functions.          |
   |------------+-----------+-----------------------------------------------|
   |            |           | Contains a subdirectory for each printer      |
   |            |           | manufacturer in which other subdirectories    |
   |            |           | are containing DRAW files used to display     |
   |            |           | warning for the according printer. Such       |
   |            |           | warnings can be also located on manufacturer  |
   | Warnings   | Directory | directory level. In the case that the         |
   |            |           | warnings are containing text their file name  |
   |            |           | should end with the number of the related     |
   |            |           | territory (exception 1=UK). This structure is |
   |            |           | only a recommendation depending on the pathes |
   |            |           | used inside functions.                        |
   +------------------------------------------------------------------------+

  The cartridge database

   The cartridges database is located inside the text file
   "<PrtInfo$Dir>.Resources.CtrInfo". Each line of the file contains the
   cartridge type and a remark for a certain cartridge of a certain cartridge
   manufacturer of a certain printer of a certain printer manufacturer in a
   certain language.

   The names of the printer manufacturer and of the printer type must be the
   same as used at other locations (case sensitive!). They are related to the
   printer itself and not to an alias type which might have been used. The
   cartridge is determined by a hexadecimal cartridge code. The name of the
   cartridge manufacturer can be written in an arbitrary way. However it
   should be the same for all cartridges. RISC OS territory number must be
   used as language (1 for UK!). The entries are language related because
   else the remarks couldn't be read by everyone. Additionally it may happen
   that certain cartridges are not offered at some region or they are sold
   under a different name. An exception is the territory number 0 which isn't
   used by RISC OS. Such an entry will be displayed at all territories.

   About the usage of the cartridge database can be discussed. However I
   regarded it as an interesting addition which allows the displaying of the
   cartridge type together with the actual ink level or whereever required.
   The remark can be used for hints which are allowing to make a decision
   whether a cartridge will fullfil the requirements of a certain print task
   or not.

Actions

   You can perform various actions on a printer. One action consists of
   several functions. The number of possible actions is varying from printer
   to printer. All actions which can be performed on a printer are described
   inside the according command file.

   Every actions starts with a certain term followed by a ":". In some cases
   a parameter is following which contains information about the interface
   because some actions must be performed in a different way according to the
   interface or are not available on certain interfaces. Some actions for
   certain ranges must be available several times with small differences. Eg
   this situation occurs at changing of the cartridges. Terms and parameters
   are casesensitive.

   The following lines are optionally containing various functions which are
   needed to perform an action. Every line is containing exactly ne action
   with parameters. The end of an action is marked by the term "End" inside a
   line.

   Additionally the file is containing options. The format is analogue to the
   actions with the exception that an option always has parameters and will
   be never followed by any function or an "End".

   +------------------------------------------------------------------------+
   |       Tag        |       Parameter       |         Description         |
   |------------------+-----------------------+-----------------------------|
   | GetCartridgeInfo |                       | Determines the actual ink   |
   |                  |                       | level of the cartridges.    |
   |------------------+-----------------------+-----------------------------|
   |                  | Hexadecimal number of |                             |
   | ChangeCartridge  | the cartridge to      | Perfomes a change of a      |
   |                  | which this action is  | cartridge.                  |
   |                  | belonging to.         |                             |
   |------------------+-----------------------+-----------------------------|
   |                  | Hexadecimal number of |                             |
   |                  | the print head        |                             |
   | CleanHead        | (analogue cartridge)  | Cleans a print head.        |
   |                  | to which this action  |                             |
   |                  | is belonging to.      |                             |
   |------------------+-----------------------+-----------------------------|
   |                  |                       | Determines which cleaning   |
   |                  | Hexadecimal number    | levels can be selected. Bit |
   | Cleaning Levels  | representing the      | 0 corresponds to cleaning   |
   |                  | cleaning levels       | level 1 etc.. If the option |
   |                  |                       | is not present cleaning     |
   |                  |                       | level 1 is assumed.         |
   |------------------+-----------------------+-----------------------------|
   |                  |                       | Determines whether an error |
   |                  |                       | occurred, paper has been    |
   |                  |                       | inserted and the printer    |
   |                  |                       | has been activated. To      |
   |                  |   * USB               | perform this task there are |
   | GetStatus        |   * Parallel          | standardized methods        |
   |                  |   * Else              | depending on the interfaces |
   |                  |                       | (USB and parallel) which    |
   |                  |                       | are fix coded inside the    |
   |                  |                       | program. However they may   |
   |                  |                       | be expanded on demand by    |
   |                  |                       | additional functions.       |
   |------------------+-----------------------+-----------------------------|
   |                  |                       | Reset the printer into a    |
   |                  |                       | definite state similar to   |
   |                  |                       | that one after switching it |
   |                  |                       | on. To perform this task    |
   |                  |   * USB               | there are standardized      |
   | ResetPrinter     |   * Parallel          | methods depending on the    |
   |                  |   * Else              | interfaces (USB and         |
   |                  |                       | parallel) which are fix     |
   |                  |                       | coded inside the program.   |
   |                  |                       | However they may be         |
   |                  |                       | expanded on demand by       |
   |                  |                       | additional functions.       |
   |------------------+-----------------------+-----------------------------|
   |                  | Hexadecimal number of |                             |
   |                  | the print head        |                             |
   | CalibrateHead    | (analogue cartridge)  | Adjusts a printer head.     |
   |                  | to which this action  |                             |
   |                  | is belonging to.      |                             |
   |------------------+-----------------------+-----------------------------|
   | PrintTestpattern |                       | Prints a nozzle check       |
   |                  |                       | pattern.                    |
   |------------------+-----------------------+-----------------------------|
   |                  | Hexadecimal number of |                             |
   |                  | the print head        | Performes a change of a     |
   | ChangeHead       | (analogue cartridge)  | print head.                 |
   |                  | to which this action  |                             |
   |                  | is belonging to.      |                             |
   |------------------+-----------------------+-----------------------------|
   | Switchoff        |                       | Switches the printer off.   |
   |------------------+-----------------------+-----------------------------|
   | Init             |                       | Is executed when the status |
   |                  |                       | window is opened.           |
   |------------------+-----------------------+-----------------------------|
   |                  |                       | Subroutine for arbitrary    |
   |                  | Hexadecimal number of | usage. Parameters if        |
   | Procedure        | the procedure         | required may be passed by   |
   |                  | (maximal 32).         | using the free usuable      |
   |                  |                       | variables.                  |
   +------------------------------------------------------------------------+

   In the following the allowed cartridge numbers are listed.

  Colours

   Menue entries and various variables are corresponding to the colours.
   There are following colours:

   +--------------------------+
   | HexValue |    Colour     |
   |----------+---------------|
   | 0x00     | Black         |
   |----------+---------------|
   | 0x01     | Cyan          |
   |----------+---------------|
   | 0x02     | Magenta       |
   |----------+---------------|
   | 0x03     | Yellow        |
   |----------+---------------|
   | 0x10     | Grey          |
   |----------+---------------|
   | 0x11     | light Cyan    |
   |----------+---------------|
   | 0x12     | light Magenta |
   |----------+---------------|
   | 0x13     | light Yellow  |
   +--------------------------+

  Cartridges

   Each colour can occur as a single cartridge. Additionally there are some
   cartridges which are containing several colours. The cartridge numbers are
   also used for head selection. Usually there is a relation between this
   however it may vary in detail. Like at the colours menue entries and
   various variables are corresponding to the cartridges. There are following
   cartridges:

   +------------------------------+
   | Hexvalue | kind of cartridge |
   |----------+-------------------|
   | 0x30     | All together      |
   |----------+-------------------|
   | 0x31     | All Blacks        |
   |----------+-------------------|
   | 0x32     | All colours       |
   +------------------------------+

Functions

   Functions and variables names are case sensitive. Every function is
   located in a seperate line inside a command file.

   +------------------------------------------------------------------------+
   | Tag  |              Parameter              |        Description        |
   |------+-------------------------------------+---------------------------|
   |      |                                     |In case that the RISC OS   |
   |      |                                     |Eval expression results to |
   |      |                                     |true the given number of   |
   |      |                                     |lines will be skipped (but |
   |      |                                     |only until the next "End").|
   |      |                                     |Jumping backwards by       |
   |cgorel|number_of_lines_to_skip              |entering negative values is|
   |      |logical_RISC_OS_Eval_expression      |allowed also. The RISC OS  |
   |      |                                     |Eval expression can make   |
   |      |                                     |usage of RISC OS system    |
   |      |                                     |variables like territory.  |
   |      |                                     |You can access PrtInfo     |
   |      |                                     |variables by preceeding    |
   |      |                                     |them with "<PrtInfo$V_".   |
   |------+-------------------------------------+---------------------------|
   |      |                                     |Sends a control sequence to|
   |      |                                     |the printer. The sequence  |
   |      |                                     |is defined by single Bytes |
   |      |                                     |which are represented by   |
   |send  |sequence_in_printer_definition_format|decimal numbers or by      |
   |      |                                     |chracters which are        |
   |      |                                     |enclosed by "". Numbers and|
   |      |                                     |characters must be         |
   |      |                                     |separated by ",".          |
   |------+-------------------------------------+---------------------------|
   |      |                                     |Fetches a response from the|
   |      |                                     |printer (if possible) into |
   |      |                                     |the variable RESPONSE.     |
   |      |                                     |0-values will be replaced  |
   |      |                                     |by spaces. The string will |
   |      |                                     |be terminated at the given |
   |      |                                     |termination character. If a|
   |      |                                     |negative values is given as|
   |      |                                     |termination character, this|
   |get   |termination_character                |indicates that the printer |
   |      |                                     |will transmit the length of|
   |      |                                     |the string at the beginning|
   |      |                                     |(as Big endian and in that |
   |      |                                     |number of Bytes which is   |
   |      |                                     |given as the absolut value |
   |      |                                     |of the negative termination|
   |      |                                     |character value). These    |
   |      |                                     |Bytes will not be          |
   |      |                                     |transfered into RESPONSE.  |
   |------+-------------------------------------+---------------------------|
   |      |                                     |Loads a DRAW file at the   |
   |      |                                     |given overlay display      |
   |      |                                     |position. In case that a   |
   |      |                                     |file already exists at this|
   |show  |overlay_position file_name           |position it will be        |
   |      |                                     |overwritten. During the    |
   |      |                                     |loading process tagged     |
   |      |                                     |objects will be scaled or  |
   |      |                                     |filled with the text of the|
   |      |                                     |given PrtInfo variable.    |
   |------+-------------------------------------+---------------------------|
   |      |                                     |Deletes a DRAW file at the |
   |      |                                     |given overlay diplay       |
   |hide  |overlay_position [upwards]           |position and in case that  |
   |      |                                     |"upwards" is given also all|
   |      |                                     |subsequent DRAW files.     |
   |------+-------------------------------------+---------------------------|
   |      |                                     |Stopps the execution of the|
   |      |                                     |action and updates the mask|
   |      |                                     |according the variables.   |
   |      |[label_button_1] [label_button_2]    |After pressing of one of   |
   |ask   |[label_button_3]                     |the buttons the execution  |
   |      |                                     |of the action will be      |
   |      |                                     |continued. The button      |
   |      |                                     |labels can be also filled  |
   |      |                                     |by program earlier.        |
   |------+-------------------------------------+---------------------------|
   |      |                                     |Splits the content of the  |
   |      |source_variable target_variable_1[   |given PrtInfo text source  |
   |split |target_variable_2 ...[               |variable according the     |
   |      |target_variable_n]] # scanf_term     |given scanf term into the  |
   |      |                                     |given target variables.    |
   |------+-------------------------------------+---------------------------|
   |      |                                     |Evaluates the expression   |
   |      |                                     |and puts the result into   |
   |      |                                     |the given PrtInfo variable.|
   |      |                                     |The RISC OS Eval expression|
   |eval  |target_variable                      |can access RISC OS system  |
   |      |RISC_OS_Eval_expression              |variables like eg          |
   |      |                                     |territory. You can access  |
   |      |                                     |PrtInfo variables by       |
   |      |                                     |preceeding them with       |
   |      |                                     |"<PrtInfo$V_".             |
   |------+-------------------------------------+---------------------------|
   |      |                                     |Executes a RISC OS command.|
   |system|RISC_OS_Command                      |You can access PrtInfo     |
   |      |                                     |variables by preceeding    |
   |      |                                     |them with "<PrtInfo$V_".   |
   |------+-------------------------------------+---------------------------|
   |      |                                     |Executes another action as |
   |      |                                     |subprogram. Beneath the    |
   |      |                                     |usual printer actions this |
   |      |                                     |can be also one of the     |
   |action|Action_Name:[ Parameter]             |"Procedure"-subprograms. At|
   |      |                                     |actions which are          |
   |      |                                     |connection type related you|
   |      |                                     |must not give the          |
   |      |                                     |connection type.           |
   +------------------------------------------------------------------------+

  Variables

   Variables are giving the programs the required flexibility. Some variables
   are connected with certain elements inside the status window or with
   certain functions. You can access PrtInfo variables inside RISC OS
   evalutions or commands by preceeding them with "<PrtInfo$V_".

+---------------------------------------------------------------------------------+
|  Variable   |Array index|   Type   |                Description                 |
|-------------+-----------+----------+--------------------------------------------|
|             |           |          |Programs should store the actual ink level  |
|             |hexadecimal|          |of the cartridges inside this variables.    |
|COL_         |cartridge  |Integer   |Value 1024 is maximum (=100%). In case that |
|             |number     |          |you are using this variable inside DRAW     |
|             |           |          |files as groupname the related objects will |
|             |           |          |be scaled accordingly.                      |
|-------------+-----------+----------+--------------------------------------------|
|CTRMAN       |           |49        |cartridge manufacturer. Is selected by the  |
|             |           |characters|user.                                       |
|-------------+-----------+----------+--------------------------------------------|
|             |hexadecimal|          |Filled by PrtInfo in accordance with the    |
|CTRTYP_      |cartridge  |19        |cartridge data base and the selected        |
|             |number     |characters|cartridge manufacturer and contains the type|
|             |           |          |of the cartridge.                           |
|-------------+-----------+----------+--------------------------------------------|
|             |hexadecimal|          |Filled by PrtInfo in accordance with the    |
|RMRK_        |cartridge  |39        |cartridge data base and the selected        |
|             |number     |characters|cartridge manufacturer and contains a       |
|             |           |          |remark.                                     |
|-------------+-----------+----------+--------------------------------------------|
|MESSAGE      |           |49        |Is displayed in the field under the three   |
|             |           |characters|indicators in the status window.            |
|-------------+-----------+----------+--------------------------------------------|
|             |           |          |Is displayed in the field above the three   |
|DIALOGMESSAGE|           |49        |buttons in the status window in dialogue    |
|             |           |characters|mode. Afterwards it is automatically        |
|             |           |          |cleared.                                    |
|-------------+-----------+----------+--------------------------------------------|
|             |           |          |During dialogue mode the content of this    |
|             |           |          |fields is displayed inside the three buttons|
|             |           |          |at the end of the status window. Afterwards |
|             |           |          |the variables are automatically cleared. the|
|             |           |          |variables can be loaded by using the        |
|             |           |          |function "ask" or can be filled by          |
|             |           |          |evaluation. There is the following scheme of|
|             |           |          |assigment to the buttons:                   |
|             |           |          |                                            |
|             |           |          |+------------------------------------------+|
|             |           |          || Maximal |  Array   |  Array   |  Array   ||
|DIALOGBUTTON_|0-2        |19        ||   not   | element  | element  | element  ||
|             |           |characters||  empty  | assigned | assigned | assigned ||
|             |           |          ||  array  |   left   | central  |  right   ||
|             |           |          ||  value  |  button  |  button  |  button  ||
|             |           |          ||---------+----------+----------+----------||
|             |           |          || 0       |          |          |          ||
|             |           |          ||---------+----------+----------+----------||
|             |           |          || 1       |          | 0        |          ||
|             |           |          ||---------+----------+----------+----------||
|             |           |          || 2       | 0        |          | 1        ||
|             |           |          ||---------+----------+----------+----------||
|             |           |          || 3       | 0        | 1        | 2        ||
|             |           |          |+------------------------------------------+|
|-------------+-----------+----------+--------------------------------------------|
|             |           |          |After finishing the dialogue mode it takes  |
|             |           |          |the information about the button which has  |
|             |           |          |been pressed at termination of the dialogue |
|             |           |          |mode. At start of the dialogue mode this    |
|DIALOGRESULT |           |Integer   |value will be set to 0.                     |
|             |           |          |                                            |
|             |           |          |  * left button sets Bit 0                  |
|             |           |          |  * central button sets Bit 1               |
|             |           |          |  * right button sets Bit 2                 |
|-------------+-----------+----------+--------------------------------------------|
|             |           |255       |Takes the result of the function "get" which|
|RESPONSE     |           |characters|are replies of the printer. 0-values will be|
|             |           |          |replaced by spaces.                         |
|-------------+-----------+----------+--------------------------------------------|
|MANUFACTURER |           |49        |Printer manufacurer, not a perhaps existing |
|             |           |characters|alias mapping. Set by PrtInfo.              |
|-------------+-----------+----------+--------------------------------------------|
|PRINTERTYPE  |           |49        |Printer type, not a perhaps existing alias  |
|             |           |characters|mapping. Set by PrtInfo.                    |
|-------------+-----------+----------+--------------------------------------------|
|             |           |          |Contains the interface used by the printer. |
|             |           |          |Allowed values are:                         |
|             |           |          |                                            |
|INTERFACE    |           |255       |  * Arbitrary                               |
|             |           |characters|  * Parallel                                |
|             |           |          |  * USB                                     |
|             |           |          |                                            |
|             |           |          |Set by PrtInfo.                             |
|-------------+-----------+----------+--------------------------------------------|
|             |           |          |Contains the protocol used by the printer   |
|             |           |          |interface. Allowed values are:              |
|             |           |          |                                            |
|             |           |          |  * Empty, if arbitrary input and output is |
|PROTOCOL     |           |255       |    possible.                               |
|             |           |characters|  * Output, if only output available        |
|             |           |          |  * Nibble, in case of parallel interface   |
|             |           |          |  * ECP, in case of parallel interface      |
|             |           |          |                                            |
|             |           |          |Set by PrtInfo.                             |
|-------------+-----------+----------+--------------------------------------------|
|             |           |          |Contains the requested cleaning level.      |
|             |           |Integer   |According to it the driver will choose the  |
|CLEANINGLEVEL|           |1-6       |control sequences. In the case that no      |
|             |           |          |choice between several levels is possible it|
|             |           |          |will contain the value 1.                   |
|-------------+-----------+----------+--------------------------------------------|
|             |           |          |The action "GetStatus" puts the standard    |
|             |           |          |printer state at here in case that an USB or|
|             |           |          |parallel interface is used. The value can be|
|             |           |          |changed also by functions. The bits are     |
|             |           |          |relating to the indicators inside the status|
|             |           |          |window.                                     |
|             |           |          |                                            |
|ERROR        |           |Integer   |+-----------------+                         |
|             |           |          || Bit |           |                         |
|             |           |          ||-----+-----------|                         |
|             |           |          || 3   | Error     |                         |
|             |           |          ||-----+-----------|                         |
|             |           |          || 4   | Activated |                         |
|             |           |          ||-----+-----------|                         |
|             |           |          || 5   | Paper     |                         |
|             |           |          |+-----------------+                         |
|-------------+-----------+----------+--------------------------------------------|
|TEXT_        |0-3        |255       |Text variables for free usage by the        |
|             |           |characters|programs.                                   |
|-------------+-----------+----------+--------------------------------------------|
|INT_         |0-3        |Integer   |Integer variables for free usage by the     |
|             |           |          |programs.                                   |
+---------------------------------------------------------------------------------+

DRAW files

   During certain actions DRAW files can be displayed inside the status
   window for explanation purposes by using the "show"-function. Upto 10 of
   such files can be overlayed in the status window. Eg you can use this
   feature for a schematic display of an operation which must be performed
   manually on the printer or to show the actual ink levels of the
   cartridges.

   During the loading the file will be examined for groups. In case that a
   group has a name it will be examined whether this group name matches a
   Prtinfo variable. If this is the case the following will happen. Every
   text inside the group will be replaced by the content of the variable.
   Integer variables will be converted. In the case that a group name starts
   with "SC_" followed by an orientation and after a "_" by a name of an
   integer variable so all path-objects inside the group will be scaled. An
   integer value of 1024 relates to 100% which means that the objects will be
   displayed in original size. The scalings will be done independently for
   each path. The orientation consists of two characters. The first one
   describes the scaling of the x coordinates and the second one the scaling
   of the y coordinates of the path. The following values can be used for the
   orientation characters:

   +------------------------------------------------------------------------+
   | Character |    Scaling description     |                               |
   |-----------+----------------------------+-------------------------------|
   |           | The relation point for the |   | The relation point for    |
   | P         | scaling is the right or    | N | the scaling is the left   |
   |           | the top edge of the        |   | or the bottom edge of the |
   |           | boundingbox.               |   | boundingbox.              |
   |-----------+----------------------------+-------------------------------|
   |           | The relation point for the |                               |
   | M         | scaling is centre of the   |                               |
   |           | boundingbox.               |                               |
   |-----------+----------------------------|                               |
   | K         | The objects are not scaled |                               |
   |           | into this direction.       |                               |
   +------------------------------------------------------------------------+

   The DRAW files will be displayed 1:1 inside the status window. Therefore
   the drawings must be located at the left bottom border. Regarding the
   extension you can help yourself by shifting the DRAW window above a status
   window. Take into account that DRAW files are having a transparent
   background by default. This is very useful because so you can overlay them
   without problems. Eg you can use this behaviour for showing warnings
   inside a cartridge ink level diagram in case that some levels fall below a
   certain level. It is also possible to generate an instruction explaining
   the changing of a cartridge at which the lowest display level shows a
   printer without cover and without cartridges. The cover or the cartridges
   are displayed on demand by overlay.

   I don't know whether it is possible to name groups inside DRAW files in
   !Draw. !Artworks allows the naming of such groups but doesn't save the
   information at DRAW export. Note that DRAW files which are generated by
   Artworks are in conjunction with the RISC OS DRAW module one of the last
   big adventures of our time. I don't now which part is responsible for it
   but the redraw handling won't work properly. So the only chance to name a
   group is to load the DRAW file into a good text editor like !Zap or
   !StrongEd and to overwrite the 12 spaces of the according groups. In
   theory you can limit a group to a single object but this requires a big
   effort so that it is better to attach an invisible dummy object to each
   object which shall be used as a group.

Other remarks

   Modern ink jet printers are build in a cost optimized way. Therefore they
   are no longer containing a paper end sensor which was available in old
   models. Because of this you will detect that there is no paper isnide the
   printer after you started your print request and not as it would be useful
   before doing so.

   The most models of Canon won't note inside the printer how much ink has
   been used. Instead Canon provides a true sensor which indicates that the
   ink level has fallen below a certain limit. Canon provides an ink level
   display under Windows but this is mamaged by the Windows printer driver
   and is thereofr not available on other machines. If you are operating such
   printers on a printer switch with several machines it is likely that the
   Windows ink level display will show you wrong values. Opposite to this
   EPSON maintians the ink levels inside the printer. However I think they
   are doing so mainly because of blocking the customers from cheap refilling
   of the cartridges. The acording commands for reseting the ink level
   counters are not documented. In consequence the EPSON printer are not
   providing cost optimized an absolut ink level sensor.
