                       FileInfo II v3.41 & Pic Viewer v1.30
                       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                 (c) 1993-2000 Thierry Godefroy, adapted from the
                     original Wolfgang Lenerz' FileInfo thing.


CONTENTS:
=-=-=-=-
                1.- LEGAL STUFF
                2.- QUICK START GUIDE
                3.- PURPOSE OF FILEINFO THINGS AND DEFINITIONS
                4.- SYSTEM REQUIREMENTS AND INSTALLATION
                5.- FILEINFO II CONFIGURATION
                6.- FILEINFO II IMPLEMENTATION
                7.- FILEINFO II ALGORITHM
                        7. 1.- "Normal" action types
                        7. 2.- "S*BASIC command" action type
                        7. 3.- "Execute file" action type
                        7. 4.- "Pick job" action type
                        7. 5.- "View file" action type
                8.- THE "FILEINFO II HISTORY" THING
                9.- THE "FILEINFO II THREAD" THING
               10.- PICTURES DISPLAYING
               11.- SBASIC PROCEDURES AND FUNCTIONS
                       11. 1.- FI2_INFO$ function
                       11. 2.- FI2_CALL, FEX and FEX_W procedures
                       11. 3.- FI2_FCALL, FEXF and FEXF_W functions
                       11. 4.- FI2_ACTN% function
                       11. 5.- FI2_PARM$ and FEX$ functions
                       11. 6.- FI2_SCAN% function
                       11. 7.- FI2_NEXT$ function
                       11. 8.- FI2_SCAN$ function
                       11. 9.- FI2_DATA function
                       11.11.- FI2_MAKE function
                       11.11.- FI2_LINK function
                       11.12.- FI2_UNLK function
                       11.13.- FI2_LOAD function
                       11.14.- FI2_SAVE procedure
                       11.15.- FI2_HCTL procedure
                       11.16.- FI2_HCTL% function
                       11.17.- FI2_HMAX procedure
                       11.18.- FI2_HMAX% function
                       11.19.- FI2_HCLR procedure
                       11.20.- FI2_HGET% function
                       11.21.- FI2_HGET$ function
                       11.22.- FI2_HMNU% function
                       11.23.- FI2_REDO procedure
                       11.24.- FI2_FREDO function
                       11.25.- FI2_HTDY procedure
                       11.26.- FI2_THRD procedure
                       11.27.- FI2_FTHRD function
               12.- INFORMATION FOR PROGRAMMERS
                       12. 1.- The FileInfo II version number
                       12. 2.- The FileInfo II thing
                       12. 3.- The "FileInfo II thread" thing
                       12. 4.- The "FileInfo II database" thing
                       12. 5.- The "FileInfo II history" thing
                       12. 6.- The "FileInfo II extensions" thing
                       12. 7.- Using the C68 "libfi2_a" library
               13.- HISTORY OF FILEINFO II
               14.- HINTS AND TIPS
                       14. 1.- Using FileInfo II history
                       14. 2.- The good usage of the "joker" extension
                       14. 3.- Writing utilities for use with FileInfo II:
                       14. 4.- Using  FileInfo II  with  some  FileInfo  unaware
                               programs
                       14. 5.- FileInfo II  friendly  installation  of  your own
                               software
               15.- THANKS !


1.- LEGAL STUFF:
    ~~~~~~~~~~~
a.- Copyright notice:
    ~~~~~~~~~~~~~~~~
This software is  a freeware, it is  NOT in the public domain.  This software is
copyright (c) 1993-1999 Thierry Godefroy, all rights reserved in all countries.

You are granted a restrictive and limited license to:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - use this  software free  of charge  for  your own  usage and/or  in your  own
   programs (including commercial and shareware programs);

 - make as many copies of this software as you like;

 - give  to others as  many copies of  this software as  you like, by  any means
   you like (BBS, Internet, disks, CD-ROM, software libraries, etc...);

provided however that:
~~~~~~~~~~~~~~~~~~~~~
 - when you incorporate my software into yours, this is mentioned;

 - any  copy given  to another  person be entire  and unmodified,  i.e. contains
   all the unmodified files of this software, including this copyright notice;

 - any copy  given to  another  person  be so  on a non-profit  and  no  benefit
   basis (i.e. you may charge for the media and mailing costs ONLY);

 - you do not  claim for any ownership / rights on this  software and you do not
   place any restriction on its further distribution.

b.- Disclaimers:
    ~~~~~~~~~~~
The  author cannot  be  held liable  for  any  loss or  damage  -direct or  not-
resulting from the use of this  program or its documentation. Although carefully
tested, this  program is not guaranteed  being bug free. This  software is free,
use it at your own risks or just don't use it at all.


2.- QUICK START GUIDE:
    ~~~~~~~~~~~~~~~~~
- Basic users should read carefully chapters 3, 4, 5 and 10.  Once they got grip
  on the FileInfo II basic concepts,  they also should read chapter 6  and 7, 8,
  9 and 14  so to discover  more advanced features and  to make use  of the full
  FileInfo II power.

- Advanced users should read chapters 3 to 10 and 14.  Chapter 11 may also be of
  some interest to them.

- Programmers should read the whole manual.


3.- PURPOSE OF FILEINFO THINGS AND DEFINITIONS:
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Wolfgang Lenerz' idea was to give to QDOS  and compatible systems the ability to
"execute"  data files  (i.e.  to start  automatically  the application  to which
belong each data file and then automatically load/process it). This facility was
already implemented into "lesser operating systems" (Wolf's words... and I fully
agree with him !)  such as Ataris TOS/GEM or,  more recently,  Windoze (I do not
know about MACs, but they should have this facility as well).

Each data file type is identified by its unique extension.  Extensions are file-
name suffixes;  they may be made up of one  to four alphanumeric  characters and
are prefixed with a separator (either "_" or ".").  E.g. in  "flp1_my_file_ext",
the extension is "ext".

When a job (the "calling job") invokes FileInfo, passing it the name of the file
to "execute" (called the "file to process" in this document), the FileInfo thing
is responsible  for launching  the right  application  and for instructing  this
application to load/process the given file.
In order to do that,  FileInfo uses its database that holds a list of the diffe-
rent  extensions  together with  some sundry  information  about  the associated
applications.  This database  is system and user-dependent  and thus  fully user
configurable.

The original FileInfo thing allowed for only one application to be associated to
each extension  (example: "txt" was associated with an editor  and "asm" with an
assembler).  FileInfo II v2.4  did extend  a bit this concept with "double link"
extensions  (each  extension  could  be associated  with  two  applications  and
FileInfo II  was able to choose which one to launch depending on the calling job
name).
FileInfo II v3.xx goes even further  by associating  an arbitrary  number (up to
32767 !) of "actions" to each extension. When comes the time to "execute" a file
with such a multiple actions extension, FileInfo II v3.xx first determines which
actions  are  eligible  depending  on the calling  job name  and on  the file to
process type;  it then presents the user  with a menu  holding  all the possible
actions (if only one action is possible then no menu is presented  and the given
action is automatically executed by FileInfo II); the user may then choose which
action is to be taken at that moment (for example, a file with a "bas" extension
may be either edited, LOADed, LRUNed or compiled).

In order to make this possible,  I had to change the FileInfo II database format
which is now as follow:

For each extension,  FileInfo II v3.xx associates one or several "actions".  For
each action, the following fields are maintained:

 - The "action name"  (which will be presented  to the user  into a menu if more
   than one action is possible in the given context).

 - An "action type" (which decides how FileInfo will handle the file).

 - Some  "action flags"  (these flags  determine  some additional  behaviours of
   FileInfo which  are not dependent  on the  "action type").  The current known
   flags are:

   - the "retain/exclude if equal" flag  (depending on this flag,  the action is
     either  retained in,  or excluded from  the possible  actions list  if  the
     calling job name is equal to the name in the "mandatory/forbidden job name"
     field).

   - the "file type flags".  One of these flags (the "mandatory file type" flag)
     tells to FileInfo II if the type of the file to process is to be taken into
     account or not for the action election.
     If this flag  is set then four other flags give  the file type number which
     is required;  FileInfo II knows about file type 255 (directory) and 0 to 14
     (only file types 255, 0, 1 and 2 are normally used under QDOS/SMS).

   - the channels redirection flags.  Two of them tell  to FileInfo II  how many
     processing  job channels  are to be redirected  (0 to 3).  Four other flags
     tells FileInfo II  to which channel  this redirection must be done;  either
     the calling job channel or a S*BASIC (job 0) channel (from #1 to #15).

   - the "pick back" flag (when this flag is set, the calling job is picked back
     before  FileInfo II returns).

   - the "wait for job termination"  flag  (when this  flag is set,  FileInfo II
     waits  for the processing job  to terminate  before  returning back  to the
     calling job).

   - the "history" flag:  when set,  the  action  is  never  recorded  into  the
     "FileInfo II history".

 - A "mandatory/forbidden job name":  this name is compared to the "calling job"
   name and depending on one "action flag", the action is either retained in, or
   excluded from,  the possible actions list.  If this name  is an empty string,
   then the action will be retained whatever is the calling job name.

 - A name of  "associated thing/job"  (which is to be awaken/picked  in order to
   process the file).

 - An "associated program filename" (to be executed  to process  the file if the
   "associated thing/job" is not found).

 - An "associated command line" (to send to the associated thing/job/program in
   order to load the file to process).

Apart from this  special database format,  FileInfo II obeys to Wolfgang Lenerz'
FileInfo specifications  and is then fully  upward compatible  with the original
FileInfo things and with previous FileInfo II things. The FileInfo II configura-
tor (called "FI2config") even gives you the possibility  to import old FileInfo/
FileInfo II  database  formats  and  automatically  converts  them into  the new
FileInfo II v3.xx format (please read carefully FI2config_help before attempting
to configure FileInfo II !).


4.- SYSTEM REQUIREMENTS AND INSTALLATION:
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FileInfo II is a "thing"  (in fact it holds  six things,  see below for details)
and then needs  for the thing system to be present into your system  (it is part
of the HotKey system II  but is also distributed  as a freeware separately;  you
will find it on most QL dedicated BBSs).

FileInfo II  also needs for PTR_GEN  (pointer  environment)  as it uses extended
screen driver calls.

Although  not mandatory,  the QMenu extensions  (copyright Jochen Merz Software)
are very desirable as FileInfo II  and Pic Viewer make use of the file selector,
the item selector, the read string menu, the view file menu and the Scrap exten-
sions that are all part of QMenu.
If QMenu is not loaded  in your system  then FileInfo II v3.xx will be unable to
present a menu in order for you to choose between  all the possible actions.  It
will therefore launch the first possible action  (thus defaulting to FileInfo II
v2.4 behaviour)...  Also the "execute file" and "view file" action types will be
affected ("execute file" will not accept  a command line,  and "view file"  will
not work at all, reporting a "not implemented" error).  IMPORTANT NOTICE: please
get the latest QMenu release (7.00 or later).
Of course,  in order to use QMenu,  you will also have to load WMAN (the pointer
environment window manager) first (it should be loaded just after PTR_GEN).

FileInfo II itself does not use the Toolkit II  but you will need it in order to
configure the FileInfo II database with "FI2config" (see below).

Finally you will need a program that makes use of FileInfo (FileInfo alone is of
no use at all). At the time being the following programs are using it:

 - QPac2 files menu (up to v1.38 you will need to apply QPAC2patch),
 - Cueshell (v2.13+.  Note that there is still a bug into Cueshell that prevents
   to use FileInfo from it on _bas files),
 - QD (QD 2 and higher),
 - Archivers Control Panel (ACP v3.0+),
 - PWfile,
 - DM5,
 - Qascade (v1.07+),
 - View (v2.18+),
 - The Shell (Adrian Ives').
 - FiFi (v4.17+).
 - My port of MicroEMACS v4.00.
 - QMenu file selector (v7.5+).
 - Msearch.
 - C68Tool2.

IMPORTANT NOTICE:  QPac 2  (v1.38  and earlier)  does not obey  Wolfgang Lenerz'
FileInfo specifications  (a fixed key value of 4  is passed to FileInfo whatever
is the actual  maximum key value allowed);  this is to say that  you will not be
able to take benefit of the "multiple actions" from the "Files" menu.
If  you  got such  a  buggy  version,  you  may  patch  your  QPac 2  copy  with
"QPAC2patch_obj" so that it may be used with FileInfo II v3.xx (the patched copy
will not work any more with older FileInfo things though).

In order  to  install  FileInfo II,  you  will  have  to load  it as  a resident
extension by typing-in "LRESPR FileInfo2_bin" (provided that the DATA_USE direc-
tory holds "FileInfo2_bin",  else prefix this name  with the appropriate device/
directory name).
Once it is loaded YOU WILL HAVE TO CONFIGURE IT ONCE  to meet your system requi-
rements (and personal taste).
Once FileInfo II  is configured as you like,  you can save it from FI2config and
add a line  into your boot file  in order to load "FileInfo2_bin"  as a resident
extension on each further system boot.


5.- FILEINFO II CONFIGURATION:
    ~~~~~~~~~~~~~~~~~~~~~~~~~
FileInfo II v3.41 is to be configured with FI2config v2.30. Please read the file
"FI2config_help" (either with an editor or within FI2config itself) for informa-
tion about configuration.  Please have a look to the original configuration held
into "FileInfo2_bin" (it's the one I use every day), it could well give you some
ideas and/or help you to understand how FileInfo II works.

The "FileInfo2_bin"  file may  also be configured  for your  particular language
with (Menu)config  (level 1).  This is important  for the "System asleep" QPAC 2
button name as this name may be different for french or german QPAC 2 versions.
You may also use (Menu)config in order to configure some preferences such as the
Qmenu item selection method (underlined first character of each item,  or selec-
tion keystrokes in front of each item), the menu item justification scheme (left
justified or centered), the history default control flags value  and the file to
process name reminder (displayed together with the "Actions" menu).


6.- FILEINFO II IMPLEMENTATION:
    ~~~~~~~~~~~~~~~~~~~~~~~~~~
The "FileInfo2_bin" file contains six things and some S*BASIC extensions.

The first thing  is FileInfo II itself  (the thing name is "FileInfo") and is to
be used in the same way as older FileInfo things.
It is also implemented  as a "QD2M" thing  and is then  directly  usable from QD
without the help  of the "QD2FI" thing  (which was mandatory in order to use the
original FileInfo from QD). If you want to use FileInfo II from QD you just have
to configure  the later so  NOT to use the "QD-FileInfo" thing (which is a dummy
FileInfo thing allowing to load all data files  into QD whatever is their exten-
sion) and to enter "FileInfo" as the name for the "F10" item.
With QD5,  the "QD5T"  thing appeared  and allows a smoother  interface with QD.
FileInfo II is still a "QD2M" thing; if you want to take benefit of the new QD5T
things with FileInfo II,  you may use QD2FI2, the latest QD2FI thing distributed
together with Wolfgang Lenerz'  FileInfo v2.04.  You will then have to configure
QD to use the "QD2FI" thing when pressing F10 instead of the "FileInfo" thing.

The second thing is the "FileInfo II database"  that holds  all the data used by
both "FileInfo" and "FileInfo II extensions" things.

The third thing  is the "FileInfo II history"  that holds records  of previously
executed FileInfo II actions.

The fourth thing  is "FileInfo II extensions".  This is a collection  of utility
vectors  that provide an easier and cleaner way of calling FileInfo,  as well as
FileInfo II database  and history  manipulation routines.  These utility vectors
are implemented as an extension thing.

The fifth  thing  is the executable  thing  "FileInfo II thread"  that allows to
call FileInfo II from any software supporting  executable things.  This thing is
also capable to send SMSQ/E  events to the calling job  (the event number may be
made dependent on the error code returned by FileInfo II).

The sixth thing  is the executable thing "Pic Viewer"  that provides easy screen
dumps/"pic-image files" viewing/pasting (through the scrap).

For  details  about  how all  theses  "things"  are to  be used  from  assembler
and C programs, see the "PROGRAMMERS INFORMATION" section.

The S*BASIC extensions allow to use FileInfo II via the "FileInfo II extensions"
from S*BASIC. See "S*BASIC EXTENSIONS" for details on how to use them.


7.- FILEINFO II ALGORITHM:
    ~~~~~~~~~~~~~~~~~~~~~
When calling FileInfo, the calling job must provide a pointer on the name of the
file to process,  a key  (from 0 to 8 for FileInfo II v3.4+, this key determines
which facilities of FileInfo are to be used)  and an optional console channel ID
(this was mandatory with older FileInfo things).
Usually an application using FileInfo will call it twice;  the first time with a
key of 0  in order to see  if the extension  of the file to process  is known by
FileInfo  and the second  time  with the  maximum  key value  to ask FileInfo to
"execute" the file to process.

a.- When  it is passed  the name  of the file  to process  by the  calling  job,
    FileInfo II first extracts its extension name.  Valid extensions are made up
    of one to four characters prefixed with either a "_" or a "." character.  If
    the file to process got no extension at all, then FileInfo II jumps directly
    to step "c".

b.- FileInfo II  then searches  in its database  for an extension  name matching
    the one of the file to process (the search is case independent).

c.- If the extension  is not found  (or if the file  to process does not get any
    extension)  then FileInfo II  searches again  in its database for the "joker
    extension" (which name is "*"). If it finds it then the action(s) associated
    with the "*" extension  will be used  for the processing  of this data file.
    This allows to take  a default action for files with unknown  extension (you
    may,  for example,  configure FileInfo II  so that it loads the unknown data
    files into your favourite editor).

d.- If no matching extension is found, then FileInfo II will return a "bad name"
    error code to the calling job.

e.- If the extension is found,  FileInfo II scans  for all the possible  actions
    associated  with this  extension.  Each action  may be retained  or rejected
    depending  on the  (case independent)  comparison  between  the name  of the
    calling job  and the "mandatory/forbidden  job name" field  for this action;
    the "retain/exclude if equal"  action  flag  decides  if the action  must be
    retained or excluded when the names are equal.  Note that  if the actual job
    name  is longer  than the mandatory/forbidden  job name  then the comparison
    only takes place on the number  of characters corresponding to the length of
    the  mandatory/forbidden  job name  (this is to cope  with jobs  that add  a
    filename or a command line behind their actual name).  Finally,  if the man-
    datory/forbidden job name is an empty string,  then the action will be auto-
    matically retained whatever is the calling job name.
    If the "mandatory  file type" flag  is set  for an action,  then FileInfo II
    will also check for the file type of the file to process and will retain the
    action only if the file type is equal to the mandatory file type number.
    FileInfo II  then builds  an array  holding  all the names  of the  retained
    actions.

f.- Once  FileInfo II scanned  all the actions,  it looks for how many  possible
    actions (those actions which was retained) are actually listed in the array.
    If the number is zero,  then FileInfo II returns a "bad name" error code  to
    the calling job.
    If there is only one action  then this action  is automatically  elected and
    FileInfo II jumps directly to step "h".

g.- If QMenu  is not available  in the system or  if the calling job specified a
    key value of 7 or <= 4,  then no menu is presented,  the first action in the
    array is automatically elected, and FileInfo II jumps to step "h".
    If QMenu  is available  and the  key value  is 5,  6 or 8,  then FileInfo II
    presents the user with a menu containing all the possible action names.  The
    user may then choose which action is to take place.
    If the user chose  the "ESC"  or the "OK" item  of the menu then FileInfo II
    returns immediately to the calling job with either no error ("OK") or a "not
    complete" error ("ESC").

h.- Once the action is chosen  or automatically elected,  FileInfo II then looks
    for the corresponding action fields. If the key value is zero, then FileInfo
    II returns to the calling job without error, returning back some pointers on
    the action fields.
    If the key value is not 0  then FileInfo II  checks the action type field to
    determine what  to do exactly.  Action types determine  how FileInfo II must
    handle its database fields  in order to "execute"  the file to process.  All
    the valid action types are listed below:

7.1.- "Normal" action types:
      ~~~~~~~~~~~~~~~~~~~~~
i1.- When encountering such action types, FileInfo II first searches for a thing
     which  name  is  held  into  the  "associated thing/job name" field  of the
     action.
     If the thing is not found then FileInfo II jumps directly to step "i2".
     If this is a "QD2M"  or "QD5T" thing  and if the calling job  is "QD", then
     the thing  is called directly  (with a JMP  so that  the thing  will return
     directly to the calling job).
     If this is an executable thing,  then FileInfo II sets up a new job with it
     (this job is called the "processing job") and then jumps to step "i4".

i2.- FileInfo II tries to find  an executable file  which filename  is held into
     the "associated program" field.  If the executable file is found then a new
     job (the "processing job")  is set up with it and FileInfo II jumps to step
     "i4".

i3.- If the executable  file is not found,  then FileInfo II  attempts a call to
     QMenu file selector in order  to ask the user where the executable file is.
     If either QMenu is not available,  or the calling job passed a key value of
     1, 2 or 7  to FileInfo II,  or the user chose  the "ESC"  item  of the file
     selector,  then FileInfo II returns  to the calling job  with a "not found"
     error.
     If the user gives a valid  executable filename to FileInfo II via the QMenu
     file selector,  then FileInfo II  jumps  back  to  step "i2"  with this new
     filename as a replacement for the "associated program" field.

i4.- Once the processing job is set up, FileInfo II then checks again the action
     type to see  if it must pass  the contents of the "associated command line"
     field  onto the processing  job stack  or into the processing job  keyboard
     queue.  If the associated command line is to be put into the keyboard queue
     then FileInfo II jumps to step "i6".

i5.- If the key value  is even or >= 7, then FileInfo II  puts the command  line
     onto the processing  job stack.  At this stage the processing  job channels
     redirection may also take place, depending on the action redirection flags.

i6.- FileInfo II activates the job. If the command line was already put onto the
     processing job stack, then FileInfo II jumps to step "i8".

i7.- If the key value is even or >= 7,  then FileInfo II stuffs the command line
     into the processing job keyboard queue.

i8.- FileInfo II looks for the "Pick back" flag and,  if set,  picks the calling
     job back.

i9.- FileInfo II returns to the calling job without error.

7.2.- "S*BASIC command" action type:
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This action  type allows  the association  of S*BASIC  commands  (which  will be
stuffed into the S*BASIC interpreter (job 0) keyboard queue by FileInfo II) with
an extension.

For example one can associate:

   - LRUN ""<RETURN> to "bas" extension,    | This is equivalent to the
   - QLRUN ""<RETURN> to "sav" extension,   | FileInfo v2.04 "special
   - LRESPR ""<RETURN> to "bin" extension,  | extension" types.

but also:

   - LOAD ""<RETURN> to "bas" extension,    | This is not possible with
   - DO ""<RETURN> to "cmd" extension,      | FileInfo v2.04...
   etc...

i1.- When encountering this action type,  FileInfo II first look for a job which
     name is "System asleep" (buttonized job 0; this name is configurable)  and,
     if found, kills it (thus un-buttonizing job 0).

i2.- FileInfo II  picks job 0  (S*BASIC interpreter)  and stuffs  the associated
     command line into its keyboard queue.

i3.- FileInfo II looks for the "Pick back" flag and,  if set,  picks the calling
     job back.

i4.- FileInfo II returns to the calling job without error.

7.3.- "Execute file" action type:
      ~~~~~~~~~~~~~~~~~~~~~~~~~~
The files  to be processed  with this type  of action  are EXECutable files.  An
action of this type  may  therefore only  be elected  by FileInfo II in step "e"
(see above) if the file to process is an executable file.

This action type was created for  Thor XVI because of its very special hard disk
driver.  This  driver  does not store  the files type,  length  and date  in the
directory entries (this information is stored in the file header only); so QPac2
Files menu is unable to find out  if a file is EXECutable and refuses to EXECute
it...  FileInfo II intervenes at this point to EXECute the files which extension
was associated with this action type  (you just have to associate "obj",  "exe",
"task", ... extensions with the EXECute file action type).

Of course, it is also possible to use this action type in order to EXECute files
from  non-shell programs  (i.e. programs  that does not  know how  to execute an
executable file, e.g. ACP v3.x). This action type will then be used with benefit
in association with the joker extension.

i1.- If  the key  passed by  the calling  job  was 4,  6 or 8,  then FileInfo II
     presents the user with a menu allowing to enter an optional command line.

i2.- FileInfo II then loads the file and sets up a new job with it,  puting  the
     command line on its stack  (if the command line is not empty)  and redirec-
     ting the job channels if the corresponding action flags are set.  Once this
     is done, the job is activated.

i3.- FileInfo II looks for the "Pick back" flag and,  if set,  picks the calling
     job back.

i4.- FileInfo II returns to the calling job without error.

7.4.- "Pick job" action type:
      ~~~~~~~~~~~~~~~~~~~~~~
This action type allows  to load more than one file  in one already  running job
(Xchange, Text87, MicroEMACS, etc...).
Impure  programs  (Turbo-charged  progs,  C progs  and  some others...)  are not
"Thingable"  (you cannot turn  them into  an executable thing - with  the Hotkey
system 2 for instance - because their code is not sharable). So when you want to
use  them with FileInfo  you must load a new copy  of the program  each time you
want it  to process  a new file;  this consumes  much more  memory  than with an
executable thing (which code  is shared by all jobs) and there are some programs
(Xchange  is one  of these)  that refuse  to run  with two  (or more)  copies of
themselves in memory  (for Xchange this is because  it tries to open a temporary
file "psion_xch" on ram1_;  as it is already "in use" by the first Xchange copy,
the second copy just stupidly gives up...).
The "Pick job" extension was implemented to cope with all these cases...

i1.- When  dealing with  this action  type,  FileInfo II  first  searches  for a
     running job  which name is equal  to that stored  in the "associated thing/
     job" field. If the actual job name is longer than the stored name then only
     the number of characters  of the stored name  will be relevant  (this is to
     cope with job that adds filename or data after their own name).  If the job
     exists  in memory,  then it is picked,  elected  as the processing job  and
     FileInfo II then jumps to step "i5".

i2.- FileInfo II tries to find  an executable file  which filename  is held into
     the "associated program" field.  If the executable file is found then a new
     job (the "processing job") is set up with it.
     Once the job is ready for activation, FileInfo II jumps to step "i4".

i3.- If the executable  file is not found,  then FileInfo II  attempts a call to
     QMenu file selector in order  to ask the user where the executable file is.
     If either QMenu is not available,  or the calling job passed a key value of
     7 or <= 2 to FileInfo II,  or the user  chose  the "ESC"  item  of the file
     selector,  then FileInfo II returns  to the calling job  with a "not found"
     error.
     If the user gives a valid  executable filename to FileInfo II via the QMenu
     file selector,  then FileInfo II  jumps  back  to  step "i2"  with this new
     filename as a replacement for the "associated program" field.

i4.- FileInfo II activates the job.

i5.- If the key value is even or >= 7,  then FileInfo II stuffs the command line
     into the processing job keyboard queue.

i8.- FileInfo II looks for the "Pick back" flag and,  if set,  picks the calling
     job back.

i9.- FileInfo II returns to the calling job without error.

Note that you must build a command line suitable for loading the file to process
in either the picked job  or the newly executed job...  This may be quite diffi-
cult and depends only on the program friendliness !

Here is a command line example for Xchange "_doc" files:

     2<F6><ESC><F3>SHwin1_psion_<ENTER>Nqui<ENTER>Quil<ENTER>1<F3>L<ENTER>
     ^^ ^^^^^^^  ^^ ^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^ ^^ ^^^^^^^^^^^
     || |||||||  || ||||||||||||||||||| |||||||||||||||||||||| || Load the file
     || Enter    || Set up the "help"   Startup a new "QUILL"  || to process.
     || in main  || sub-directory.      copy giving it a       ||
     || XChange  ||                     unique name: "Quil"   ++-> Pause while
     || menu.    ++-> Enter in the      will expand in QuilNNNN     QUILL is set
     ||               command mode.     where "NNNN" is a random    up.
     ||                                 number (see the special
     ++-> Pause while Xchange is        symbols section).
          set up.

This command line will appear like this in FI2config:

Pause 2sF6ESCF3SHwin1_psion_ENTERNquiENTERQuilRandom numberENTER
Pause 1sF3LdevN_name_extENTER

which is hopefully less cryptic...

7.5.- "View file" action type:
      ~~~~~~~~~~~~~~~~~~~~~~~~
This action type allows to view a file, using the view file menu of QMenu.

i1.- If the key is greater than 2 and different from 7 then FileInfo II attempts
     a call to the QMenu view file menu passing it the file to process  name. If
     QMenu is not available or the key was 1, 2 or 7,  a "not implemented" error
     is returned.

i2.- FileInfo II looks  for the "wait for processing  job termination" flag and,
     if set, waits for the user to exit the view file menu.

i3.- FileInfo II looks  for the "pick back" flag  and if set,  picks the calling
     job back.

i4.- FileInfo II returns to the calling job without error.


8.- THE "FILEINFO II HISTORY" THING:
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This thing  stores the  latest actions  executed by FileInfo II.  Each action is
stored  in one  record holding  the action  block address  and the  name of  the
processed file.
The  maximum number  of records  into the history  is configurable  by using the
"FileInfo II extensions" or the S*BASIC "FI2_HMAX" procedure.


9.- THE "FILEINFO II THREAD" THING:
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This thing allows  to call FileInfo II  as if it was  an  executable thing. This
may be particularly useful for using FileInfo II from hotkeys or QPAC 2 buttons.

Programmers will  also benefit from it  because it allows to  thread totally and
easily  the FileInfo II  processing  of files,  thus releasing  immediately  the
calling program (and  thanks to SMSQ/E events the calling  program may still get
reports about the success of the FileInfo II processing).

When started, the  "FileInfo II thread" thing takes an  optional console channel
Id and a command  line (both are to be put on its stack).  The command line must
include a  filename (the one  of the "file to  process") unless one of the "-h",
"-H" or "-s" options is in the command line  (in which case the filename will be
taken either from the history or from the hotkey stuffer buffer).  The following
options  are  also  recognized   by "FileInfo II  thread"  (the options  must be
separated from the filename and from each other by a single space, they are case
sensitive):

        -h   : pops  a menu  holding  all the records stored  in the FileInfo II
               history,  waits  for the  user  to select one  of them,  and then
               executes the associated action.
        -H   : same as "-h" but the history will be tidied up before the menu is
               presented to the user (so that the records applying to deleted or
               renamed files are removed from the history).
        -s   : instructs "FileInfo II thread"  to take the file  to process name
               from the hotkey stuffer buffer.
        -kN  : with N=0 to 8 (FileInfo II key, default is -1 i.e. maximum key).
        -w   : will set  the bit 31  of the key  (wait for processing job termi-
               nation flag).
        -eSF : with S and F from 0 to 7 or "." (no event) representing the event
               number  that will be sent  to the calling job  in case of success
               (S) or failure (F).
        -err : will send events if FileInfo II failed.  The event vector will be
               equal  to -ERNUM.  Example:  if FileInfo II  reports  "not found"
               (QDOS  error code -7),  events 0,  1 and 2  will be  sent  to the
               calling job (because 2^0+2^1+2^2=7).

One obvious  usage of the "FileInfo  II thread" thing  is to assign a  hotkey so
that the FileInfo II history  may be used.  Another very interesting usage is to
define a hotkey so that the filename held into the hotkey stuffer buffer is used
as the "file  to process" name  (this hotkey  will  therefore  allow you  to use
FileInfo II  with  all the  programs  that  are  stuffing  the  filename  of the
currently  loaded/processed  file into the hotkey buffer,  even if they were not
originally designed to use FileInfo II). See chapter 14 for details of how to do
this.

Of course  this thing may be executed  with the Hotkey System II  "EXEP" command
(e.g.  EXEP "FileInfo II thread";"win1_myfile_ext -e.0 -w"),  but I recomend you
to use the FI2_THRD/FI2_FTHRD  procedure/function instead because they will take
care of the thread name (job name) so that FileInfo II  may use it when building
the  possible  actions list  (taking  into account  the "Mandatory/forbidden job
name" field of each action).


10.- PICTURES DISPLAYING:
     ~~~~~~~~~~~~~~~~~~~
The first releases  of FileInfo II were allowing bitmap  screen dumps displaying
(such  a screen  dump may  be obtained  on an unexpanded QL  with something like
SBYTES ram1_picture_scr,131072,32768) in MODE 4, 8 or 12 (the Thor XVI 16 colors
mode) thanks to special extension types.
From FileInfo II v1.8 onwards the processing code  for picture displaying (a job
named  "Pic Viewer")  has  been  made  independent  from  the FileInfo II  thing
(although it is still part of the "FileInfo2_bin" file) and is now an executable
thing named "Pic Viewer".  This will allow to develop the two things  separately
and to use  the  "Pic Viewer"  thing  from other programs  (and from Super-BASIC
thanks to the Hotkey system 2 "EXEP" command).

When started the "Pic Viewer" executable thing  takes a command line  (to be put
on its stack).  This command  line must include the picture filename followed by
zero, one or two options  (they specify  the picture size and the screen MODE in
which  it is to be displayed).  The options must be separated  from the filename
and from each other by a space character  (here is a valid command line example:
ram1_picture_scr -m8 -ega).  The options may be written either in lower or upper
case letters.

The available options are:
~~~~~~~~~~~~~~~~~~~~~~~~~
  a.- Requested display MODE:
      ~~~~~~~~~~~~~~~~~~~~~~
      -m2   : MODE 2  (useful under SMS2 only).
      -m4   : MODE 4  (default option).
      -m8   : MODE 8
      -m12  : MODE 12 (useful on Thor XVI only).
      -m16  : MODE 16 (useful on Aurora only).

      Note that, as at the moment no Aurora extended screen driver is available,
      the MODE 16 is untested  (I also wait for the new driver  before implemen-
      ting a MODE 256 parameter in Pic Viewer).

  b.- Picture size:
      ~~~~~~~~~~~~
      -ql   : Picture size of 512x256 pixels (default option).
      -ega  : Picture size of 640x350 pixels.
      -vga  : Picture size of 640x480 pixels.
      -svga : Picture size of 800x600 pixels.
      -w768 : 768 pixels wide pictures.
      -w1024: 1024 pixels wide pictures.
      -w1280: 1280 pixels wide pictures.

   c.- Picture format:
       ~~~~~~~~~~~~~~
      -pic  : Picture in pointer environment "pic" format. This option overrides
              any other option  as this type  of picture holds  its own size and
              display mode in its header.


     The  "Pic  Viewer"  thing  automatically  recognizes  the  screen  size and
     compares it with the picture size.
     If the picture size is smaller or equal to the screen size then the picture
     will be displayed in the center of the screen.
     If the  picture size  is greater  than the  screen size  then  "Pic Viewer"
     displays the upper left corner  of the picture and allows for the screen to
     be "moved around" in the picture with cursor keys  (if <SHIFT> is used with
     cursor keys then the screen  will move by 8 pixels  at a time)  so that you
     can view any part of it.
     Depressing the <TAB>  key entitles you to store the displayed picture  into
     the "Scrap"  (part of Jochen Merz Software MENU_REXT extensions).  With the
     old "Scrap Extensions"  versions  (1.03 and before)  this feature will only
     work with pictures smaller than 32768 bytes.
     Pressing <ENTER> or <ESC> keys will exit "Pic Viewer".

     If "Pic Viewer" receives an empty command line (e.g. EXEP "Pic Viewer"), it
     will display the picture stored into the "Scrap" (if any).


     Using "Pic Viewer" from FileInfo II:
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     To use the "Pic Viewer" thing  from FileInfo II  you will have to define an
     extension name  for each picture  size and mode  and to associate  to these
     extensions the thing "Pic Viewer".  Do not give any name for the associated
     program and define the suitable command line (to be put on the stack).
     Examples:

          - Command line for "scr" extension (MODE 4, 512x256)  : 
          - Command line for "scr8" extension (MODE 8, 512x256) :  -m8
          - Command line for "sc12" extension (MODE 12, 512x256):  -m12
          - Command line for "ega" extension (MODE 4, 640x350)  :  -ega
          - Command line for "ega8" extension (MODE 8, 640x350) :  -ega -m8
          - Command line for "pic" extension ("pic" format)     :  -pic
          etc...

     Note that the "" symbol is displayed as devN_filename_ext in FI2config.


11.- SBASIC PROCEDURES AND FUNCTIONS:
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These procedures and functions are in fact calls to the "FileInfo II extensions"
utilities. They entitle you to use FileInfo II  from S*BASIC  or from a compiled
S*BASIC program.

In the following PROC/FN syntaxes, square brackets denote an optional parameter.

11.1.- FI2_INFO$ function:
       ~~~~~~~~~~~~~~~~~~
This function returns various information about FileInfo II.

Syntax: Info$=FI2_INFO$(Code)

With: Code = 0 to get back the FileInfo II version (currently "3.41").
           = 1 to get back the max key and implemented facilities (an hex number
               in the form MMMMFFFF  where MMMM is the max key value and FFFF is
               the facility bitmap word, currently 000801FF).
           = 2 to get back the database structure version (currently "FIv3").
           = 3 to get back the copyright message.

11.2.- FI2_CALL, FEX and FEX_W procedures:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Syntax: FI2_CALL [#Channel,]File_name[,Key]
    or: FI2_CALL [#Channel,]Filename$[,Key]

with  : Channel: "con_"  Super-BASIC channel  number  that will  be used  if the
                 action  redirection  flags  are set  so to use  the calling job
                 channel (if no Channel parameter is given,  then no redirection
                 will take place except  if the redirection flags  are set so to
                 redirect the processing job channel(s) to a S*BASIC channel).

       Key = 0 : to check if the file extension is recognized by FileInfo II.
           = 1 : to execute the first possible action associated program without
                 passing the associated command line to it.
           = 2 : same as 1 but the command line is passed to the processing job.
           = 3 : same  as  1  but  the  QMenu  file  selector is  called  if the
                 associated program is not found.
           = 4 : same as 2 with possible QMenu file selector calling.
           = 5 : same as 3  but if multiple actions are possible,  then FileInfo
                 II presents the user with  a menu in order to choose the action
                 to be taken.
           = 6 : Same as 5 but the command line is passed to the processing job.
           = 7 : Same as 2 but the additional parameter may  be used (if any) in
                 the command line sent to the processing job.
           = 8 : Same as 6 but the additional parameter may  be used (if any) in
                 the command line sent to the processing job.
           =-1 : (default key value).  Uses the maximum possible key (6 for this
                 version of FileInfo II).
           =-2 : same as -1  but FileInfo II  will wait  for the processing  job
                 termination before returning to the calling job.
                 Note also that you may set bit 31  of any positive key value in
                 order  to force  FileInfo II  to wait  for the  processing  job
                 termination.

Below is a summary  of what facilities are used  by FileInfo II depending on the
key value:

Key value                               | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
----------------------------------------+---+---+---+---+---+---+---+---+---+
Only check extension and return         |yes|no |no |no |no |no |no |no |no |
----------------------------------------+---+---+---+---+---+---+---+---+---+
Actually process the file               |no |yes|yes|yes|yes|yes|yes|yes|yes|
----------------------------------------+---+---+---+---+---+---+---+---+---+
Command line passed to processing job   |no |no |yes|no |yes|no |yes|yes|yes|
----------------------------------------+---+---+---+---+---+---+---+---+---+
Use QMenu (1)                           |no |no |no |yes|yes|yes|yes|no |yes|
----------------------------------------+---+---+---+---+---+---+---+---+---+
Multiple actions menu presented         |no |no |no |no |no |yes|yes|no |yes|
----------------------------------------+---+---+---+---+---+---+---+---+---+
Additional paramater taken into account |no |no |no |no |no |no |no |yes|yes|
----------------------------------------+---+---+---+---+---+---+---+---+---+
(1) i.e. file selector,  command line input  for "execute file" action and "view
    file" action available.

The name of the file  to process may be followed  by an additional  parameter in
this way:

REMark first assign the filename to a temporary string:
String$=Filename$
:
REMark if the filename length is odd then pad it with one trailing space:
IF INT(LEN(String$)/2)<>LEN(String$)/2 THEN String$=String$&" "
:
REMark now append the additional parameter prefixed with its marker:
String$=String$&"<<%FI2>>"&Parameter$
:
REMark finally, call FileInfo II:
FI2_CALL String$,Key

Please note that unlike  older FileInfo things,  you do not need any more to set
the primary window outline before using FI2_CALL.

The FEX procedure is the exact equivalent of FI2_CALL and FEX_W is equivalent to
FI2_CALL with the bit 31 of the key set  (FEX and FEX_W are kept for upward com-
patibility with older FileInfo things only;  these procedure/function should not
be used in a program that do require FileInfo II v3.00 or later).

11.3.- FI2_FCALL, FEXF and FEXF_W functions:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Syntax: Error_code=FI2_FCALL([#Channel,]File_name[,Key])
    or: Error_code=FI2_FCALL([#Channel,]Filename$[,Key])

The parameters are  the same as for FI2_CALL.  These functions are equivalent to
FI2_CALL,  FEX and FEX_W procedures but they return a QDOS error code instead of
triggering an error trap when FileInfo II fails.

Note that the returned error code  is a long word whereas older FEXF  and FEXF_W
were returning a word.

11.4.- FI2_ACTN% function:
       ~~~~~~~~~~~~~~~~~~
This function returns the number of actions associated with a given filename. It
is sensible to the calling job name as different actions may be available depen-
ding on this name.

Syntax: Max_action=FI2_ACTN%(File_name)
    or: Max_action=FI2_ACTN%(Filename$)

11.5.- FI2_PARM$ and FEX$ functions:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The FI2_PARM$  function allows  to get  the information  (stored  in FileInfo II
configurable database)  associated with a given file.  This function is sensible
to the calling job name as different actions  may be available depending on this
name.

Syntax: Parm$=FI2_PARM$(Code,File_name[,Action])
    or: Parm$=FI2_PARM$(Code,Filename$[,Action])

With  : Code = 0 : to get back the associated thing name.
             = 1 : to get back the associated executable filename.
             = 2 : returns an empty string (was formerly the 2nd exec filename).
             = 3 : to get back the associated command line.
             = 4 : to get back the mandatory or forbidden calling job name.
             = 5 : to get back the action name.
             = 6 : to get back  the action type  and action flags  (in the hexa-
                   decimal form TTTTFFFF where TTTT is the action type value and
                   FFFF is the action flags word value).

        Action = action  number  (from  1  up  to  the  number  returned  by the
                 FI2_ACTN% function). Default is 1.

The FEX$ function is equivalent  to FI2_PARM$ and is kept only for upward compa-
tibility with older FileInfo II things;  it should not be used in a program that
do require FileInfo II v3.00 or later.

11.6.- FI2_SCAN% function:
       ~~~~~~~~~~~~~~~~~~
This function  returns  the number of all  the actions  associated with  a given
extension. The returned number is NOT dependent on the calling job name.

Syntax: All_actions=FI2_SCAN%(Extension$)

Where Extension$ holds the name of the extension (1 to 4 lower case characters).

11.7.- FI2_NEXT$ function:
       ~~~~~~~~~~~~~~~~~~
This function returns the next extension in the database.

Syntax: Next_extension$=FI2_NEXT$(Extension$)

If  Extension$="FIv3" (database structure Id)  then the name of the first exten-
sion is returned.  If Extension$ is the last extension  in the database  then an
empty string is returned.

11.8.- FI2_SCAN$ function:
       ~~~~~~~~~~~~~~~~~~
This function allows to get  the information associated  with a given extension,
regardless of the calling job name.

Syntax: Parm$=FI2_SCAN$(Code,Extension$,Action)

With  : Code = as for FI2_PARM$ function.
        Extension$ = name of the extension (e.g. as returned by FI2_NEXT$).
        Action = action number (from 1 to the number returned by FI2_SCAN%).

11.9.- FI2_DATA function:
       ~~~~~~~~~~~~~~~~~
This function allows to read or set the address  of the FileInfo II configurable
database.

Syntax: Old_data=FI2_DATA(New_data)

With  : New_data = 0 to read the current data block address.
                 = address of a valid  (see programmers information for details)
                   new  database  to replace  one.  The old database  address is
                   returned by the function.

11.10.- FI2_MAKE function:
        ~~~~~~~~~~~~~~~~~
This function allows to build a new extension or action block.  This function is
to be used in order  to ensure upward  compatibility with the future FileInfo II
releases  (the database format may change  but this function  will take care for
automatic database format conversion).

Syntax: Address=FI2_MAKE(Id$,[Extension$,]Type,Flags,Name$,Job$,Thing$,File$,
                         Command$)

With  : Id$        = database format identifier (currently "FIv3").
        Extension$ = name of the extension  (to build a new extension block,  to
                     build an action block this parameter must be omitted).
        Type       = action type (see programmers info chapter for details).
        Flags      = action flags (see programmers info chapter for details).
        Name$      = action name (1 character min., 40 characters max.).
        Job$       = mandatory/forbidden job name.
        Thing$     = name of the associated job/thing to wake.
        File$      = name of the file of the associated program.
        Command$   = associated  command line  (see programmers info chapter for
                     special symbols details).

On return from this function,  the "Address" variable holds either  a QDOS error
code (if < 0)  or a valid address  on the new block (if > 0)  that is to be used
with the FI2_LINK function.
Another special syntax  is allowed ("Address=FI2_MAKE(Id$)")  in order  to build
the first (dummy)  extension block that may be linked  with FI2_DATA function so
to replace the old database contents and build a new one from scratch.

11.11.- FI2_LINK function:
        ~~~~~~~~~~~~~~~~~
This function allows  to link a new extension  or a new action  into FileInfo II
configurable database.

Syntax: Error_code=FI2_LINK([Extension$,]Address)

With  : Extension$ = name  of the extension  into which  the new action  must be
                     linked.
        Address    = address of the new action block to link or,  if Extensions$
                     was omitted, of the new extension block to link.

11.12.- FI2_UNLK function:
        ~~~~~~~~~~~~~~~~~
This function unlinks  a given extension from the FileInfo II configurable data-
base.

Syntax: Address=FI2_UNLK(Extension$)

With  : Extension$ = name of the extension to unlink.
        Address    = address of the unlinked extension block or QDOS error code.

11.13.- FI2_LOAD function:
        ~~~~~~~~~~~~~~~~~
This function allows to load and link a new configurable database in the memory.
The old database  is automatically  unlinked.  The file to load  may either hold
only the database or FileInfo II code followed with the database.

Syntax: Error_code=FI2_LOAD(#Channel[,Address])

With  : #Channel = S*BASIC channel of the file holding the database to load.
        Address  = base  address  of the zone  where the new  database  is to be
                   loaded (this zone must be  big enough to hold  the whole file
                   and  must  be at least  64 bytes long).  If "Address"  is not
                   supplied then FI2_LOAD will allocate a zone by itself.

11.14.- FI2_SAVE procedure:
        ~~~~~~~~~~~~~~~~~~
This procedure allows to save either FileInfo II code,  FileInfo II database, or
both.

Syntax: FI2_SAVE #Channel,Code

With  : #Channel = S*BASIC channel open  on the file  in which FileInfo II is to
                   be saved.
        Code     = 0 to save both FileInfo II code and data.
                 = 1 to save FileInfo II code only.
                 = 2 to save FileInfo II data only.

11.15.- FI2_HCTL procedure:
        ~~~~~~~~~~~~~~~~~~
This procedure  allows to set  the control flags  for the "FileInfo  II history"
thing.  There is  currently only  one  flag that  toggles the  recording of  the
actions executed by FileInfo II.

Syntax: FI2_HCTL Flag

With  : Flag = 0 to disable actions recording.
             = 1 to enable actions recording.

11.16.- FI2_HCTL% function:
        ~~~~~~~~~~~~~~~~~~
This function returns the current value of the FileInfo II history control flags
word.  Currently, only  0 (action  recording  disabled) or  1 (action  recording
enabled) may be returned.

Syntax: Flag=FI2_HCTL%

11.17.- FI2_HMAX procedure:
        ~~~~~~~~~~~~~~~~~~
This procedure sets  the maximum number of records allowed  into the FileInfo II
history (1 to 32767).

Syntax: FI2_HMAX Max_records

11.18.- FI2_HMAX% function:
        ~~~~~~~~~~~~~~~~~~
This function reads  the current value of the maximum  number of records allowed
into the FileInfo II history.

Syntax: Max_records=FI2_HMAX%

11.19.- FI2_HCLR procedure:
        ~~~~~~~~~~~~~~~~~~
This procedure clears all the records from the FileInfo II history.

Note that FI2_DATA (when New_data<>0),  FI2_UNLK and FI2_LOAD are doing implicit
calls to this procedure (this prevents to have records of discarded actions into
the history).  FI2_HMAX also calls this function implicitly when the new maximum
number  of records  in history  is set to  a smaller value  than the old maximum
value.

Syntax: FI2_HCLR

11.20.- FI2_HGET% function:
        ~~~~~~~~~~~~~~~~~~
This function returns the number of records stored into the FileInfo II history.

Syntax: N_Records=FI2_HGET%

11.21.- FI2_HGET$ function:
        ~~~~~~~~~~~~~~~~~~
This  function  allows  to  retrieve  the  action  name,  the  filename  and the
additional parameter from a given FileInfo II history record.

Syntax: Name$=FI2_HGET$(Key,Record)

With  : Key = 1 to retrieve the action name,
            = 2 to retrieve the filename.
            = 3 to retrieve the additional parameter.

        Record = record number (1st record = 0, last record = FI2_HGET%-1).

11.22.- FI2_HMNU% function:
        ~~~~~~~~~~~~~~~~~~
This function presents  the user with a  menu holding all records  (in the form:
"<Action name>  <filename>") and waits  for the user to  select one of  the menu
item. The  function then  clears the menu  and returns the  record number  (0 to
FI2_HGET%-1), -1 (if  the "ESC" item was  selected) or -2 (if the  "OK" item was
selected or if the history is currently empty).

Syntax: Record=FI2_HMNU%

11.23.- FI2_REDO procedure:
        ~~~~~~~~~~~~~~~~~~
This procedure allows to re-do an action recorded into  the FileInfo II history.
The parameters are  much the same as  for FI2_CALL but the  filename is replaced
with the record  number. Note that when re-doing an action, no check  is made by
FileInfo II on the calling job name nor on the file type of the file to process.

Syntax: FI2_REDO [#Channel,]Record[,Key]

With  : #Channel = as for FI2_CALL.
        Record   = record number (0 to FI2_HGET%-1).
        Key      = as for FI2_CALL.

11.24.- FI2_FREDO function:
        ~~~~~~~~~~~~~~~~~~
This function has the same effect as FI2_REDO but it returns the error code from
FileInfo II.

Syntax: Error_code=FI2_FREDO([#Channel,]Record[,Key])

With same parameters as for FI2_REDO.

11.25.- FI2_HTDY procedure:
        ~~~~~~~~~~~~~~~~~~
This procedure tidies  the "FileInfo II history"  by removing records associated
with deleted or renamed files.

Syntax: FI2_HTDY

11.26.- FI2_THRD procedure:
        ~~~~~~~~~~~~~~~~~~
This  function  sets  and  starts up  a new  job using  the "FileInfo II thread"
executable thing. The advantage in using it over the Hotkey system 2 "EXEP" pro-
cedure is that it adjusts automatically the thread name  to the calling job name
(the thread  name  will  be  "<calling job name> (FileInfo II thread)"  or  only
"FileInfo II thread" if the calling job got no name);  this entitles FileInfo II
to take  the calling job name  into account  when building  the possible actions
list  (using the "forbidden/mandatory job name"  field  of  the action  blocks).
Moreover  you may  adjust  the thread  priority  and choose  to wait  for thread
completion or not thanks to the "Timeout" parameter.

Syntax: FI2_THRD [#Channel,]Command_string$[,Timeout[,Priority]]

With  : #Channel        = as for FI2_CALL.
        Command_string$ = command string for "FileInfo II thread" (see chap. 9).
        Timeout         = -1 to wait for thread completion  (and inherits thread
                             error). Default is 0.
                           0 to proceed without waiting (no error inheritance).
        Priority        = thread priority (0 to 127), default is 8.

11.27.- FI2_FTHRD function:
        ~~~~~~~~~~~~~~~~~~
This  function has  the same effect  as FI2_THRD  but it returns  the error code
instead of triggering and error trap.

Syntax: Error=FI2_FTHRD([#Channel,]Command_string$[,Timeout[,Priority]])

With same parameters as for FI2_THRD.


12.- INFORMATION FOR PROGRAMMERS:
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~
12.1.- FileInfo II version number:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~
The FileInfo II  version number will,  from v3.00 upward,  obey to the following
rules:  the version number  is in the form "R.ub"  where "R",  "u"  and "b"  are
digits (from 0 to 9) with the following meaning:

  - "R" is the release number:  each time a major upgrade to FileInfo II will be
    needed,  this number will be incremented.  A new release will also mean that
    the FileInfo II database structure changed since the last release.
  - "u" is the update number:  each time  a minor update  to FileInfo II will be
    needed, this number will be incremented. There will NOT be any change to the
    overall FileInfo II  database  structure  (i.e. the fields number,  type and
    size will not change),  but some additional  action flags  may be added,  or
    some fields meaning/usage may change slightly.
  - "b" is the bugfix number:  each time  a bugfix  will be needed,  this number
    will be incremented. No change in FileInfo II database nor behaviour will be
    made. This digit may also be a "" to denote a beta release of FileInfo II.

The  FileInfo II  (i.e.  "FileInfo",  "FileInfo II extensions " and "FileInfo II
thread" things) version number is printed on #0 each time FileInfo II is loaded.
The "FileInfo II extensions"  thing version  will also be kept in sync with this
number  so that it may be obtained easily  from a program;  this is to say  that
even if no change was made  into the "FileInfo II extensions" thing itself since
the last release,  its version  number  will change  to reflect  the FileInfo II
version.

12.2.- FileInfo II thing (the name of the thing is "FileInfo"):
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to call the FileInfo thing,  an application should first call the thing
use TRAP/vector (SMS.UTHG) with the following parameters:

Call parameters  :   D0.L = $28 (SMS.UTHG).
~~~~~~~~~~~~~~~      D1.L = job Id or -1.
                     D3.L = timeout.
                     A0.L = pointer to name of thing ("FileInfo").

Return parameters  : D0.L = error code.
~~~~~~~~~~~~~~~~~    D2.L = absolute pointer to FileInfo linkage block.
                     D3.L = version of thing (max key in MSW, bitmap in LSW).
                     A1.L = address of thing.
                     A2.L = absolute pointer to FileInfo code.

Preserved registers: D1, D4 to D7, A0, A1, A3 to A7.
~~~~~~~~~~~~~~~~~~~

The address returned in A2 is the absolute address of the thing code, to which a
JSR  should be made IN USER MODE.  Indeed,  the thing code will normally attempt
to start a job.  This (in QDOS) is only possible  from USER MODE and thus cannot
be done directly  in the  SMS.UTHG call,  the latter always  being  performed in
supervisor mode.

There are  some  differences  between  the FileInfo II v3.xx  thing code and the
older FileInfo things:

   - Compared with FileInfo,  FileInfo II returns (when key=0) two more pointers
     (A3 and D3).  This does not affect the use  of the FileInfo thing as anyway
     A3 and D3 are documented as being corrupted by the original FileInfo.

   - The console  channel Id  is now  optional  (it was  mandatory  in the older
     FileInfo things). If you do not get an Id to pass, just pass -1 instead.

   - There is no more need for setting the outline of the calling job when using
     key values greater than 2  (this is because FileInfo II now calls QMenu via
     a child job which outline is set to the whole screen area).

   - There  is no  more risk  of a calling  job stack overflow  when FileInfo II
     invokes QMenu  (QMenu eats up  a lot of stack  but it  is now called  via a
     child job which stack is big enough).

   - FileInfo II also accepts an additional parameter  (to be passed immediately
     after the file  to process name:  see below for details),  that may be used
     into the processing job command string, thus altering its behaviour.

Here are the parameters for the thing code:

Call parameters    : D1.L = calling job console channel Id or -1.
~~~~~~~~~~~~~~~      D2.L = pointer to FileInfo linkage block.
                     D3.L = key determining what facility is to be used.
                     A0.L = pointer to the filename of the "file to process".
                            This string may be immediately  followed  (on a word
                            boundary) by a magic word ($4AFB), the '%FI2' marker
                            and  a QDOS  string holding  an additional parameter
                            that may be used into the command string).

Return parameters  : D0.L = error code.
~~~~~~~~~~~~~~~~~    D2.L = if key=0: 0 (formerly ptr / 2nd program filename),
                            else    : corrupted.
                     D3.L = if key=0: ptr on associated command string or 0,
                            else    : corrupted.
                     A2.L = if key=0: ptr on associated program filename or 0,
                            else    : corrupted.
                     A3.L = if key=0: ptr on associated thing name or 0,
                            else    : corrupted.

Preserved registers: D4 to D7, A0, A4 to A7.
~~~~~~~~~~~~~~~~~~~

- Key values:

On entry,  D3.L  must contain  a key  indicating  which part  of the services of
FileInfo is to be used:

Key value       Action

    0           Only searches  for the first possible action associated with the
                file to process and returns pointers on associated data for this
                action.

    1           Try to execute the first possible action but do not put anything
                into the keyboard queue or onto the stack of the processing job.
                QMenu is never used with this key.

    2           Execute the first possible action and put the associated command
                line into the keyboard queue or onto the stack of the processing
                job. QMenu is never used with this key.

    3           Same as 1 but,  if no file or thing to execute is found then use
                QMenu (if present)  to invite the user  to select  an executable
                file.

    4           Same as 2 but,  if no file or thing to execute is found then use
                QMenu (if present)  to invite the user  to select  an executable
                file.

    5           Same as 3 but, if more than one action is possible,  present the
                user with a menu (if QMenu was loaded) in order  to choose which
                action is to be taken.

    6           Same as 4 but, if more than one action is possible,  present the
                user with a menu (if QMenu was loaded) in order  to choose which
                action is to be taken.

    7           Same as 2 but,  if an additional parameter  is passed behind the
                file  to process name,  allow its usage  in the  command string.
                QMenu is never used with this key.

    8           Same as 6 but,  if an additional parameter  is passed behind the
                file to process name, allow its usage in the command string.

Additionally (when key>0),  the bit 31  of the key may be set  in order to force
FileInfo to wait for the processing job termination before returning back to the
calling job.

Further values may also be added  in future releases.  However,  any application
can always  easily use  all the  facilities  of the latest  release  of FileInfo
thanks  to the MS word  of the thing  version number  returned  in D3  after the
SMS.UTHG call  (this MS word just holds  the highest key allowed by FileInfo).
Here is the way to use the highest possible key with any FileInfo thing:

          [ SMS.UTHG call ]
          CLR.W     D3                  Eliminate the bitmap.
          SWAP      D3                  Maximum key into LS word.
          .../...                       Fill in the other registers.
          JSR       (A2)                Call FileInfo code.

The version number returned after the SMS.UTHG call also contains in its LS word
a bitmap of the supported facilities.  Thus,  your  code may  check  whether the
facility to be used is present in this version of the thing (with "BTST #key,D3"
if the bit is set then the facility is implemented).

If a key  of a determined  value  is allowed,  then  ALL LOWER KEYS WILL ALSO BE
ALLOWED  (although  it is not required  that all  lower facilities  are actually
implemented).

- Thus,  the total code  to call FileInfo could be  as follow  (assuming that A5
points to the thing vector and D7 holds your channel Id or -1 for no channel).

FI_CALL   LEA       FI_NAME,A0          Pointer to the name of the thing.
          MOVEQ     #-1,D1              Job Id (current job).
          MOVEQ     #-1,D3              Infinite timeout.
          MOVEQ     #$28,D0             | SMS.UTHG (use the thing).
          JSR       (A5)                |
          TST.L     D0                  Error ?
          BNE.S     ERROR               If yes then process it.
          LEA       FILENAME,A0         Pointer to the name of file to process.
          MOVE.L    D7,D1               Calling job "con_" channel Id (or -1).
          CLR.W     D3                  Clear the LSW (bitmap of facilities).
          SWAP      D3                  Key = maximum key.
          JSR       (A2)                Call FileInfo.
          MOVE.L    D0,D6               Keep error code.
          LEA       FI_NAME,A0          Pointer to the name of the thing.
          MOVEQ     #-1,D1              Job Id (current job).
          MOVEQ     #$29,D0             | SMS.FTHG (free the thing).
          JSR       (A5)                |
          MOVE.L    D6,D0               Get error code back.
          BNE.S     ERROR               If any error, process it.
          .../...

FI_NAME   dc.w      8
          dc.b      'FileInfo'

Please note that this way  of calling FileInfo II is only kept for compatibility
reasons.  There is now a much more cleaner and easier way to call FileInfo II by
using  the 'CALL' extension  (see "FileInfo II  extensions" chapter).  Each time
your software does require  FileInfo II v3.00  or later,  you should use the new
calling method.

12.3.- The "FileInfo II thread" thing:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This executable thing  provides an other way  to call  FileInfo II  as well as a
convenient threading mechanism for software using FileInfo II.

It may be passed one or two parameters: a console channel Id (which will be pas-
sed to FileInfo II) and a command string.  Please refer to chapter 9 for details
on the command line arguments.

12.4.- The "FileInfo II database" thing:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This thing holds the FileInfo  configurable database.  It is used  internally by
the "FileInfo"  and  "FileInfo II extensions"  things.  You should never  use it
directly from your code unless you  explicitly want to lock the database so that
nobody can change its contents  (as long as the "FileInfo II database"  thing is
in use, the database cannot be changed via the "FileInfo II extensions").

The FileInfo  database structure is dependent  on the FileInfo release  and thus
may change again in the future. The  changes will remain transparent to the user
(thanks to FI2config).  As a programmer, in order to  keep upward compatibility,
you should use the "FileInfo II  extensions" thing to manipulate the FileInfo II
database. It is intended that future  FileInfo II versions will provide an auto-
matic  database format  conversion mechanism  through the  'MAKE' extension.  To
ensure upward compatibility, it is therefore  mandatory to use this extension in
order to build extensions/actions (for example if you want to link automatically
new extensions from your software installation program; an example of a FileInfo
II installation  set of  routines is  given in the  "util_WL_" directory  of the
FileInfo II  archive. Thanks must  go to Wolfgang Lenerz  who wrote this  set of
routines).

The database is divided into extension blocks.  There is at least  one extension
block, the dummy one  which is mandatory.  There is no limit on extension blocks
number. Extension blocks are not necessarily contiguous in memory. This entitles
to add easily extension blocks to an existing database.

Each extension block  is then divided  into an extension header  and one or more
action blocks.  There must be at least one action block in each extension block.
The maximum number  of action blocks in each extension block is 32767.  Only the
first action block has  to be contiguous  with  the associated  extension  block
header in memory,  the other action blocks  may be located  anywhere  in memory.
This allows to add easily new actions to an existing extension.  Each pointer in
an extension block is relative to the extension block header address.

Here is the overall database structure:

FI_DATA   dc.b      'FIv3'                        | This first (dummy) extension
          dc.l      EXT1-FI_DATA                  | block is mandatory. It holds
          dc.w      0                             | the database structure Id
          dc.l      0                             | and allows to 'UNLK' the
          dc.w      0,0,0,0,0,0,0                 | 1st (true) extension block.

* Header of the first extension block:

EXT1      dc.b      'xxxx'                        Extension name (see note 1).
          dc.l      EXT2-EXT1                     Pointer to next ext. (or 0).
          dc.w      N_actions                     Number of associated actions.

* First action block for EXT1 (must follow immediately the extension block
* header).

ACT11     dc.l      ACT12-EXT1                    Pointer to next action (or 0).
          dc.w      ActionType                    Action type (see note 2).
          dc.w      SpecialFlags                  Special flags (see note 3).
          dc.w      ActNameLength                 | Name of this action (see
          dc.b      'Action name'                 |  note 4).
          dc.w      CallingJobNameLength          | Name of the mandatory or
          dc.b      'CallingJobName'              |  forbidden calling job name.
          dc.w      ThingNameLenght               | Name of the associated thing
          dc.b      'ThingName'                   |  to execute.
          dc.w      PgmFilenameLength             | Filename of the associated
          dc.b      'PgmFilename'                 |  program to execute.
          dc.w      CmdLineLength                 | Associated command line.
          dc.b      'CmdLine'                     |

* the next action blocks are not necessarily contiguous in memory.

ATC12     .../...

* extension blocks are not necessarily contiguous in memory.

EXT2      dc.b      'yyyy'
          dc.l      EXT3-EXT2
          dc.w      N_actions

ACT21     dc.l      ACT22-EXT2
          .../...


Note 1 : the extension name must be  in lower case letters,  right justified and
         zero filled.  Only  alphanumeric  characters  (a-z and 0-9)  should  be
         allowed  (although  no check  is made  for this  in  existing  FileInfo
         things), the only exception being the "joker" extension ("*").

Note 2 : here are the valid action type values:

           0 : "normal" action type, put the command line into keyboard queue.
           1 : "normal" action type, put the command line onto stack.
         -10 : "S*BASIC command" action type;
         -11 : "EXECute file" action type;
         -12 : "Pick job" action type.
         -13 : "View file" action type.

Note 3 : here is the structure of the action flags word:

         bit 15..............bit 0
                            
              ccccH0nnttttTRPW

         with: cccc = channel  number  (%0000  to %1111).  If  cccc=0  then  the
                      calling  job  channel  is  used  (if available);  else the
                      S*BASIC channel  (1 to 15)  is used  (if open,  else #0 is
                      used).

               nn   = number of channels to pass (%00 to %11)  on the processing
                      job stack.

               tttt = required file type (%0000 to %1111).  If tttt=15  then the
                      required file type is actually 255 (directory type).

               H    = 0 do not disable  the recording  of this  action  into the
                        FileInfo II history.
                      1 disable  this  action  recording  into  the  FileInfo II
                        history.

               T    = 0 do not check for the file type.
                      1 check for the file type.

               R    = 0 exclude this action  if the calling job name is equal to
                        the string held  into  the mandatory/forbidden  job name
                        field.
                      1 retain this action  if the calling job name  is equal to
                        the string held  into  the mandatory/forbidden  job name
                        field.

               P    = 0 do not pick the calling job back.
                      1 pick the calling job back.

               W    = 0 do not wait  for processing job termination  (unless the
                        bit 31 of the key is set).
                      1 wait for the processing job termination (whatever is the
                        value for the bit 31 of the key).

Note 4: the action names length  is bounded  by a minimum  of 1 character  and a
        maximum of 40 characters.

Special symbols for the associated command lines:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The associated command line is a string of characters.  All these characters but
the special symbols are sent "as is" to the processing job.  The special symbols
are either replaced by a string or trigger some special features of FileInfo.
You  do not  need to learn  all  these symbols  because  they are  automatically
inserted  by "FI2config"  when you choose  the appropriate items  in the command
line input menu.
You  must  know  though  that there  is no fall-trough  possibility  (i.e. these
symbols  are always  replaced  by their actual  meaning);  as these  symbols are
rather rarely used characters, this should not be a problem at all. Moreover you
must know what facility they offer to you. So here they are:

"" : this  symbol  is  replaced  by the  name  of the  file  to  process  (e.g.
      win1_filepath_myfile_ext).

"" : this symbol  is replaced by the name  of the file  to process  without its
      extension (e.g. win1_filepath_myfile).

"" : this symbol  is replaced by the name  of the file  to process  without the
      device name (e.g. filepath_myfile_ext).

"" : this symbol  is replaced by the name  of the file  to process  without the
      device name and without its extension (e.g. filepath_myfile).

"" : this symbol is replaced by a random four digits number (0000 to 9999).

"n": ("n" is a number from 1 to 9).  This symbols instructs FileInfo II to mark
      a pause of "n" seconds before sending  the next characters  of the command
      line (this symbol  is only active for action types  that stuff the command
      line into the keyboard queue).

"": this symbol  is replaced  by the  optional  additional  parameter  that the
     calling job may send to FileInfo II (see below).

"": this symbol  denotes  the begining  of a  conditional  part  of the command
     string;  if an additional parameter was sent  to FileInfo II by the calling
     job,  then the characters and  symbols enclosed between "" and "" will be
     included into the command string, else they are ignored.

"": this symbol marks the end of the conditional part of the command string.

You may  have  noticed  that  these symbols  are different  from those  of older
FileInfo  things.  This  should  not  be a problem  as  FI2config  automatically
converts old symbols to the new ones  (also turning the old channel  redirection
symbols into the corresponding action flags).

Additional parameter:
~~~~~~~~~~~~~~~~~~~~
This feature is new in FileInfo II v3.40+ and allow calling jobs to pass another
parameter  (to be used  into the  command  string  sent  by  FileInfo II  to the
processing job).  This additional parameter is to follow immediately the file to
process name  and must  be prefixed  with $4AFB  and '%FI2'  (aligned  on a word
boundary. Example:

        dc.w    9                               | QDOS string holding the file
        dc.b    'win1_boot'                     |  to process name.
        dc.b    0                               Word aligment byte.
        dc.w    $4AFB                           Magic word.
        dc.b    '%FI2'                          Additional parameter marker.
        dc.w    12                              | QDOS string holding the
        dc.b    'My parameter'                  |  additional parameter.

Using the "",  ""  and ""  symbols into the command string,  you may use this
additional parameter  in order to alter  the processing job behaviour.  E.g. you
may want to put the following command string when "QD" is used as the processing
job:

 \s 

(in FI2config this command line will be displayed as:
 devN_name_extIF additional parameter \s additional parameterEND IF )

This will expand  to the file to process name  (i.e. instructing QD to edit this
file) and, if -and only if- an additional parameter is passed, the filename will
be followed  by " \s <parameter string>" (therefore QD,  after loading the file,
will also search for  the first occurrence  of the string  corresponding to this
parameter).

12.5.- The "FileInfo II history" thing:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This thing is a linked list of  records holding the action block address and the
name of the processed file of any successfully executed FileInfo II action;  the
executed actions  are recorded  into the history provided  that the same  record
does not already exists and that the FileInfo II history is enabled (both system
wide and for the given action).  Note that the additional parameter is not taken
into account when searching for an already existing record.

The maximum number of records in the history is configurable (both as default in
the FileInfo2_bin file config  block and at run time via  the FileInfo II exten-
sions thing).  Whenever the number of records in the  history reaches its limit,
the oldest record is discarded each time a new one is stored.

The information held in each record may  also be extracted using the FileInfo II
extensions thing. The  extensions thing also provides routines  for clearing the
history and setting the control flags of  the thing (at the time being, only one
flag is in use and allows to enable/disable the history).

When the "FileInfo II history" thing  is disabled, the existing records are kept
in the history but no new record  is added until the thing is enabled again.  It
is still possible to  use the thing and extract information from  it while it is
disabled.

12.6.- The "FileInfo II extensions" thing:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This thing is a collection of utility vectors that provide for an easy and clean
FileInfo II interface.

When dealing  with FileInfo II  database and/or history manipulations,  you MUST
use these vectors  in order to ensure upward compatibility  with future FileInfo
II releases.

Note that  "FileInfo" and "FileInfo II extensions"  things use the  "FileInfo II
database" thing  each time their code  is entered and  free it on return  to the
calling job.  This allows for  the "FileInfo II extensions"  to check whether or
not they can change (atomically, i.e. in supervisor mode) the FileInfo II confi-
gurable database (if the  "FileInfo II database" is used by another job  when an
attempt is  made to  change the  database contents,  then an  "in use"  error is
returned and  no change  is made  to the  database). It  is then  perfectly safe
to use the "FileInfo II extensions" in order to modify the database, while it is
not when attempting to do so from your own routines. The modifications performed
on  the FileInfo  II history  thing are  also made  in supervisor  mode and  the
history is cleared each time one or  more actions are unlinked from the FileInfo
II database.

a.- Calling the "FileInfo II extensions" from your code:
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
IMPORTANT: All the "FileInfo II extensions" must be called in USER MODE ONLY.

There are several ways of calling these extensions.  The first one is to put the
desired extension Id into D2.L and then use (SMS.UTHG trap/vector) the "FileInfo
II extensions".  This will return the extension thing address  into A1.L and you
will then just have  to fill-in the registers  with the adequate  parameters and
to do a JSR $18(A1) (because A1 is usually a parameter itself,  you will have in
fact to store the extension thing address into another register, e.g. A4, before
filling-in the registers with parameters).  On return you will then have to free
the "FileInfo II extensions".  Thus the code  should be  (assuming that A5 holds
the thing vector address):

USE_xxxx  LEA       FI2EXT,A0                     Pointer on thing name.
          MOVE.L    #'xxxx',D2                    Extension Id (name).
          MOVEQ     #-1,D1                        Use for current job.
          MOVEQ     #-1,D3                        Infinite timeout.
          MOVEQ     #$28,D0                       | SMS.UTHG (use the thing).
          JSR       (A5)                          |
          TST.L     D0                            Error ?
          BNE.S     ERROR                         If yes, process it.
          LEA       $18(A1),A4                    Vector for 'xxxx' extension.
          .../...                                 Fill-in the parameters here.
          JSR       (A4)                          Call the thing.
          MOVE.L    D0,D7                         Keep error code.
          LEA       FI2EXT,A0                     Pointer on thing name.
          MOVEQ     #-1,D1                        Free for current job.
          MOVEQ     #$29,D0                       | SMS.FTHG (free the thing).
          JSR       (A5)                          |
          MOVE.L    D7,D0                         Restore error code.
          BNE.S     ERROR                         If error, process it.
          .../...

FI2EXT    dc.w      22                            | Thing name.
          dc.b      'FileInfo II extensions'      |

Of course this method is good  when you call only  one extension but it is quite
heavy when you want  to issue several  extension calls.  The "FileInfo II exten-
sions" therefore provide an easier  and much more efficient  way to use them;  a
special extension which Id is 'VECT',  entitles you to call all the other exten-
sions with just one universal vector. Here is the way to use it:

USE_MANY  LEA       FI2EXT,A0                     Pointer on thing name.
          MOVE.L    #'VECT',D2                    Extension Id.
          MOVEQ     #-1,D1                        Use for current job.
          MOVEQ     #-1,D3                        Infinite timeout.
          MOVEQ     #$28,D0                       | SMS.UTHG (use the thing).
          JSR       (A5)                          |
          TST.L     D0                            Error ?
          BNE.S     ERROR2                        If yes, process it.
          LEA       $18(A1),A4                    Universal vector.
          .../...                                 Fill-in the parameters here.
          MOVE.L    #'xxxx',D0                    Id of 1st extension to use.
          JSR       (A4)                          Call the thing.
          BNE.S     ERROR                         If error, process it.
          .../...                                 Fill-in the parameters here.
          MOVE.L    #'yyyy',D0                    Id of 2nd extension to use.
          JSR       (A4)                          Call the thing.
          BNE.S     ERROR                         If error, process it.
          .../...                                 Fill-in the parameters here.
          MOVE.L    #'zzzz',D0                    Id of 3rd extension to use.
          JSR       (A4)                          Call the thing.
          BNE.S     ERROR                         If error, process it.
          .../...                                 etc...
ERROR     MOVE.L    D0,D7                         Save error code.
          LEA       FI2EXT,A0                     Pointer on thing name.
          MOVEQ     #-1,D1                        Free it for current job.
          MOVEQ     #$29,D0                       | SMS.FTHG (free the thing).
          JSR       (A5)                          |
          MOVE.L    D7,D0                         Restore error code.
ERROR2    .../...

Here is the register usage for the 'VECT' extension:

Call parameters  : D0.L = Id of the extension to be called (e.g.: 'CALL').
~~~~~~~~~~~~~~~    D1 to D3 and A0 to A3: parameters  required  by the extension
                                          to be called.

Return parameters: D0.L = error code (-19 if the called extension does not exist
~~~~~~~~~~~~~~~~~         or any other error code returned  by the called exten-
                          sion).
                   D1 to D3 and A0 to A3: parameters  returned   by  the  called
                                          extension.
                   D4 to D7 and A4 to A7: preserved.

Finally,  note that whatever  the method for calling  the extensions you choose,
you should always use (SMS.UTHG) the "FileInfo II extensions" BEFORE calling one
or more of its vectors and free it (SMS.FTHG)  once all the calls are completed.
This will ensure,  in the event  the thing is removed  by another job,  that the
jobs using it  will also be removed  (thus preventing a crash because of the old
thing code being overwritten and then executed).

b.- 'INFO' extension (get information about FileInfo II):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension returns some sundry information about FileInfo II.

Call parameters  : none.
~~~~~~~~~~~~~~~

Return parameters: D0.L = QDOS error code.
~~~~~~~~~~~~~~~~~  D1.L = accepted database Id (version), currently 'FIv3'.
                   D3.L = maximum  key  value  allowed  (MS word)  and bitmap of
                          implemented facilities (LS word).
                   A0.L = pointer on the copyright message (QDOS string).
                   D2, D4 to D7 and A1 to A7 : preserved.

c.- 'CALL' extension (call the "FileInfo" thing code):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension provides for an easy call to the FileInfo thing code. Two new key
values  are allowed  when calling "FileInfo"  via this extension: -1 that stands
for "maximum key value allowed" and -2  (same as -1 but the key bit 31 will also
be set  so that FileInfo  will wait  for the processing job  to terminate before
returning).  Also this routine  takes care  of using  and freeing the "FileInfo"
thing  so you do not have  to bother with this.  Finally,  the register usage is
optimised so that more of them are preserved.

Call parameters  : D1.L = "con_" channel Id or -1 if no channel.
~~~~~~~~~~~~~~~    D3.L = key: >= 0 : normal FileInfo keys (bit 31 may be set).
                                 -1 : maximum allowed key value.
                                 -2 : as -1 but with bit 31 set.
                   A0.L = pointer to the name (string)  of the file  to process.
                          This string  may  be immediately  followed  (on a word
                          boundary)  by a magic word ($4AFB),  the '%FI2' marker
                          and  a QDOS  string  holding  an additional  parameter
                          that may be used into the command string).


Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D2.L = if key=0: 0 (formerly ptr on 2nd program filename),
                          else    : corrupted.
                   D3.L = if key=0: ptr on 1st action command string or 0,
                          else    : corrupted.
                   A2.L = if key=0: ptr on 1st action program filename or 0,
                          else    : corrupted.
                   A3.L = if key=0: ptr on 1st action thing/job name or 0,
                          else    : corrupted.
                   D1, D4 to D7, A0, A1 and A4 to A7: preserved.

d.- 'ACTN' extension (get number and names of possible actions):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension builds a QDOS array holding all the names of the possible actions
and returns the address of this array as well as the number of actions in it.

The array is an array of strings;  although  the string  dimension  is set to 44
characters,  only 40 characters  are actually  available  for each  action  name
because the last four bytes of each string hold the absolute address of the cor-
responding action block.  You should  not use  this address  in order to extract
yourself  information  from the action block  as the action block  structure may
change in future FileInfo II  releases;  you must use the 'PARM' extension to do
this.

After calling this extension and extracting  all the desired parameters with the
'PARM' extension,  you must use the 'FREE' extension in order to free the memory
reserved for the array and to free the "FileInfo II database" thing.

The total number  and the names of the actions  into the array  are dependent on
the calling job name as different actions may take place depending on it.

Call parameters  : A0.L = ptr on the name of the file to process (QDOS string).
~~~~~~~~~~~~~~~    D2.L = -1 (mandatory, reserved for future improvements).

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D2.W = number of associated actions for this file.
                   A1.L = pointer on the array holding the action names.
                   D1, D3 to D7, A0, A2 to A7: preserved.

e.- 'SCAN' extension (get number and/or names of all actions):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension is similar to the 'ACTN' but does not take care about the calling
job name  and thus allows  to retrieve  all the information relative  to a given
extension (it also returns  the next extension name  in the database so that the
whole database may be scanned). Moreover it does not require a filename but only
the extension name (e.g. 'asm', '*' (the joker extension), "txt", etc...).  Note
that unknown extensions will NOT be expanded to the joker ("*") extension.

Call parameters  : D1.L = extension name (lower  case letters,  right justified,
~~~~~~~~~~~~~~~           zero filled, or 'FIv3' to find the first extension).
                   D2.L = 0 to get back the next extension and actions number.
                          1 same as 0  but an array  of the action names is also
                            built.

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D1.L = name of the next action (0 if none).
                   D2.W = number of actions for the given extension.
                   A1.L = if D2.L was 1, pointer on the action names array.
                   D3 to D7, A0 and A2 to A7: preserved.

Note that the array of the action names will only be built if D2.L=1. It is also
possible  to get  the first  extension name  by calling  'SCAN' with D1.L='FIv3'
(i.e. the database structure Id as returned by 'INFO')  and D2.L=0 (as there are
no associated action  for the dummy 'FIv3' extension,  'SCAN' will return  a bad
parameter error if D2.L=1).

The array built by 'SCAN' (when D2.L=1)  got the same structure than with 'ACTN'
and may therefore be used with 'PARM'. If you called 'SCAN' with D2.L=1 then you
will have to use 'FREE' in order  to free the memory allocated for the array and
to free the "FileInfo II database" thing.

f.- 'PARM' extension (get the parameters associated with a given action):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension allows  to extract  the parameters  associated  with  each action
listed into  the array returned  by the 'ACTN' or 'SCAN' extensions.  It must be
passed the array address,  the requested parameter code number,  and an index of
the considered action in the array.  It returns a pointer on the requested para-
meter as well as the action type and action flags.

This extension cannot (obviously) be called before 'ACTN' or 'SCAN' and must not
be called after releasing the array with 'FREE'.

Call parameters  : A1.L = pointer on the actions array (as returned by 'ACTN'
~~~~~~~~~~~~~~~           extension).
                   D1.W = code number of the requested parameter:
                          0 : name of associated thing/job name.
                          1 : name of associated program file.
                          2 : empty string (formerly second program file).
                          3 : associated command line.
                          4 : name of mandatory/forbidden job name.
                          5 : name of the action.
                   D2.W = index of the considered action (1st action = 0).

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D3.L = action type (MS word) and action flags (LS word).
                   A2.L = pointer on the requested parameter.
                   D1, D2, D4 to D7, A0, A1, A3 to A7: preserved.

g.- 'FREE' extension (free the array allocated by 'ACTN' or 'SCAN'):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This  extension frees  the memory  allocated  for the array  built  by 'ACTN' or
'SCAN' and frees  the "FileInfo II database" thing  so that the database  may be
modified again.

Call parameters  : A1.L = array address as returned by 'ACTN'.
~~~~~~~~~~~~~~~

Return parameters: none, all the registers are preserved.
~~~~~~~~~~~~~~~~~

h.- 'DATA' extension (set or read the FileInfo database address):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension allows  to set or read  the FileInfo II  database  address.  When
setting the address,  A1  must point  onto  a valid  FileInfo II  database.  The
database Id  is checked  against  the current  FileInfo II  one and  an error is
returned if the Id is not matching.  Note that,  when used to set a new database
address and successful,  this extension also does an implicit call to the 'HCLR'
extension in order to clear the history.

Call parameters  : A1.L = new database address (if you want to set it),
~~~~~~~~~~~~~~~           or 0 (if you want to read the database address).

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  A1.L = if A1 was 0: current database address,
                          else       : old database address.
                   D1 to D7, A0 and A2 to A7: preserved.

i.- 'MAKE' extension (build an extension or action block):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension provides for building a new extension or action block. It returns
a pointer to the new block.  This pointer may be used  with the 'LINK' function.
It is mandatory to use this function  when building new blocks  (i.e. you should
not build them directly  from your code)  because it will implement an automatic
database format  conversion  mechanism  in the next  FileInfo II releases  (thus
ensuring upward compatibility with old software using it).

Call parameters  : D1.L = name of the extension (0 to create an action block).
~~~~~~~~~~~~~~~    D2.L = 0 if pointers are absolute, 1 if relative to A6.
                   D3.L = database format id (currently 'FIv3').
                   A0.L = pointer  (either  absolute  or relative  to A6) on the
                          table of pointers  (themselves and respectively either
                          absolute or relative to A6).

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  A1.L = absolute pointer on the new block.
                   D1 to D7, A0 and A2 to A7: preserved.

The table pointed to by A0.L must have the following structure:

          dc.w      ActionType                    Action type.
          dc.w      ActionFlags                   Action flags.
          dc.l      ActionName                    Pointer to name of action.
          dc.l      JobName                       Ptr on mandat./forb. job name.
          dc.l      ThingName                     Ptr on associated thing name.
          dc.l      FileName                      Ptr on associated file name.
          dc.l      CommandString                 Ptr/associated command string.

These pointers may be either absolute (D2.L=0) or relative to A6.L (D2.L=1). The
"ActionName" is limited to a minimum of 1 character  and a maximum of 40 charac-
ters.

A special case  (when D1.L = D3.L  i.e. when the extension name  is equal to the
database format id) entitles you to build the first (dummy) extension block that
is to be linked with  the 'DATA' extension in order  to replace the old database
contents and to build a new one from scratch.

j.- 'LINK' extension (link a new extension or a new action into the database):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension allows to link either a new extension block to the database, or a
new action block to an already existing extension block.

Call parameters  : D1.L = 0  in  order  to  link   a  new  extension  block,  or
~~~~~~~~~~~~~~~           extension name  (1 to 4 lower case  characters,  right
                          justified  and  zero  filled)  in order  to link a new
                          action block for this extension.
                   D2.L = -1 (mandatory, reserved for future improvements).
                   A1.L = address of extension or action block to link.

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D1 to D7 and A0 to A7: preserved.

k.- 'UNLK' extension (unlink an extension from the database):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension allows to unlink an extension block from the database. Note that,
when successful,  this extension also does an implicit call to the 'HCLR' exten-
sion in order to clear the history.

Call parameters  : D1.L = name  of the  extension  to unlink  (1 to 4 lower case
~~~~~~~~~~~~~~~           characters, right justified and zero filled).
                   D2.L = -1 (mandatory, reserved for future improvements).

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  A1.L = address of the unlinked extension block.
                   D1 to D7, A0 and A2 to A7: preserved.

l.- 'LOAD' extension (load a new database):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension allows to load a database from a file.  This file may be either a
"FileInfo2_bin" file  (FileInfo II code + database) or a file with  just a data-
base in it (full database only with its dummy extension at offset 0). Note that,
when successful,  this extension also does an implicit call to the 'HCLR' exten-
sion in order to clear the history.

Call parameters  : D2.L = -1 (mandatory, reserved for future improvements).
~~~~~~~~~~~~~~~    A0.L = channel Id of the file to load.
                   A1.L = base address  for database  loading or 0  if 'LOAD' is
                          to  allocate  a zone  by itself.  The zone  pointed to
                          by A1.L must  be big  enough  to hold  the  whole file
                          and must be at least 64 bytes long.

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  A1.L = new database address.
                   A2.L = old database address.
                   D1 to D7, A0 and A3 to A7: preserved.

m.- 'SAVE' extension (save the FileInfo II code and/or database):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension saves the FileInfo II code and/or database to a file.

Call parameters  : D2.W = 0 to save both the code and the data,
~~~~~~~~~~~~~~~           1 to save the code only,
                          2 to save the data only.
                   A0.L = destination file channel Id.

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D1 to D7 and A0 to A7: preserved.

n.- 'HCTL' extension (set/read the control flags of the "FileInfo II history"):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension sets or reads the "FileInfo II history" thing control flags word.
At the time being, only flag 0 is in use.

Call parameters  : D1.W = -1 to read the current flag value,
~~~~~~~~~~~~~~~            0 to disable the "FileInfo II history",
                           1 to enable the "FileInfo II history".

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D1.W = current flag value.
                   D2 to D7 and A0 to A7: preserved.

o.- 'HMAX' extension (set/read the value of max number of records in history):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension sets  or reads the "FileInfo II history"  thing number of records
limit (1 to 32767). When using this extension  to set a new value for this limit
which is smaller than the old one, then the history is cleared (implicit call to
the 'HCLR' extension).

Call parameters  : D1.W = -1 to read the current value of max number of records,
~~~~~~~~~~~~~~~            any value from 1 to 32767 to set a new limit.

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D1.W = current limit value.
                   D2 to D7 and A0 to A7: preserved.

p.- 'HCLR' extension (clears all records in FileInfo II history):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Clears all the records held in the "FileInfo II history".

Call parameters  : D2.L = -1 (mandatory, reserved for future improvements).
~~~~~~~~~~~~~~~

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D1 to D7 and A0 to A7: preserved.

q.- 'HGET' extension (get parameters held in a FileInfo II history record):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
With this  extension, you may  get the current number  of records stored  in the
"FileInfo II history"  as well as the action name,  the processed  file name and
the additional parameter for each record.

Call parameters  : D1.W = 0 to get the number of records in the history,
~~~~~~~~~~~~~~~           1 to get the action name of a record,
                          2 to get the processed filename of a record,
                          3 to get the additional parameter of a record.
                   D2.W = record number (if D1.W <> 0), counted from 0.

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D3.W = if D1.W=0: number of records in the history;
                          else     : corrupted.
                   A1.L = if D1.W=0: corrupted;
                          else     : pointer on requested name.
                   D1, D2, D4 to D7 and A0, A2 to A7: preserved.

r.- 'HMNU' extension (presents the 'FileInfo II history' menu to the user):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension only works  if JMS Menu extensions are loaded. It  pops up a menu
holding all the FileInfo II history records (in the form "<Action name> <proces-
sed filename>"), waits for  the user to select one of the  menu item and returns
the result (record number, or -1 for  "ESC", or -2 for "OK"), clearing the menu.
There is no need  to set the outline before calling  this extension (the calling
job does not even need to have an open  console channel) as it sets up a new job
(with proper  outlined console  channel) that  calls the  Menu extension  in its
turn.

Call parameters  : D2.L = -1 (mandatory, reserved for future improvements).
~~~~~~~~~~~~~~~

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D2.W = selected record number,
                       or -1 if the "ESC" item was selected,
                       or -2 if "OK" was selected (or if the history is empty).
                   D1, D3 to D7 and A0 to A7: preserved.

s.- 'REDO' extension (re-do an action stored in the "FileInfo II history"):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This  extension re-does a  given  action that  was  previously  stored into  the
history.  All the parameters  but the pointer  to the filename  of the  "file to
process" (which is replaced by the record number) are the same as for the 'CALL'
extension. Note that when re-doing an action, the file type  and the calling job
name are not taken into account.  No check is made for the existence of the file
either;  if the file does not exist any more, this will result in an error being
returned either by FileInfo II or by the processing job, depending on the action
type.  Note that if the processing job was EXECuted (wait flag of the action and
bit 31 of the key not set),  then no error will be returned by REDO but an error
will still occur in the processing job.

Call parameters  : D1.L = "con_" channel Id or -1 if no channel.
~~~~~~~~~~~~~~~    D2.W = record number (starting from 0 for 1st record).
                   D3.L = key: >= 0 : normal FileInfo keys (bit 31 may be set).
                                 -1 : maximum allowed key value.
                                 -2 : as -1 but with bit 31 set.

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D2.L = if key=0: 0 (formerly ptr on 2nd program filename),
                          else    : corrupted.
                   D3.L = if key=0: ptr on 1st action command string or 0,
                          else    : corrupted.
                   A2.L = if key=0: ptr on 1st action program filename or 0,
                          else    : corrupted.
                   A3.L = if key=0: ptr on 1st action thing/job name or 0,
                          else    : corrupted.
                   D1, D4 to D7, A0, A1 and A4 to A7: preserved.

t.- 'HTDY' extension (tidy up the records stored in the "FileInfo II history"):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extensions checks for the existence  of the files which names are stored in
the "FileInfo II history".  It tries to open each file associated with a record:
if the open call returns "not found",  the corresponding  record is removed from
the history.
Depending on how fast the directory devices are  and how much records are stored
into the history, this call may become quite time consuming.

Call parameters  : D2.L = -1 (mandatory, reserved for future improvements).
~~~~~~~~~~~~~~~

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D1 to D7 and A0 to A7: preserved.

u.- 'THRD' extension (set and start up a new "FileInfo II thread" job):
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This extension sets up  and starts a new job using the "FileInfo II thread" exe-
cutable thing. The job name will be "FileInfo II thread" if the calling job does
not get a name or  "<calling job name> (FileInfo II thread)" if it got one (this
allows FileInfo II  to use  the thread name  to build the possible  actions list
using the "forbidden/mandatory job name").
The command string is to be built according to chapter 9.

Call parameters  : D1.L = "con_" channel Id or -1 if no channel.
~~~~~~~~~~~~~~~    D2.B = thread priority.
                   D3.W = timeout: -1 the calling job is suspended until thread
                                      processing completion.
                                    0 the calling job multitasks with thread.
                   A0.L = pointer on the command string.

Return parameters: D0.L = error code.
~~~~~~~~~~~~~~~~~  D1 to D7, A0 to A7: preserved.

12.7.- Using the C68 "libfi2_a" library:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The "libfi2_" directory  of the FileInfo II  distribution holds  the sources and
binaries for the "libfi2_a" library.

In order to use it,  you will have to copy "fi2_h" into the "include_" directory
of C68 and "libfi2_a" into its "lib_" directory. <fi2.h> must be included in any
source using "libfi2_a" functions.  When linking,  you will also have to put the
"-lfi2" option into the "ld" command line.
The "fi2test_c" source (and its associated makefile) is a good example of how to
use the library.

You are allowed to change  the library sources for your own usage but you should
not distribute any modified file  (see the copyright notice in chapter 1 of this
document).  The "modules_txt" file and "libfi2make" program may be used in order
to re-build  the library  (just follow the  program instructions;  note that you
will need QMAC or the GST macro assembler as well as the C68 "slb" utility).
If you change "modules_txt",  please make sure  that "fi2subN_rel entries  (with
N=1 to 3) are listed last, or the resulting library will fail at link time (for-
ward references are not supported by "ld").

The "libfi2_asm" file may also be used  to build a position  independent version
of the library  (it will assemble  into "libfi2_rel"  and will  then have  to be
renamed as "libfi2_a"), the only draw back being that whatever library functions
you will use, the whole library (about 2Kb) will be linked to your program.

Hereafter are listed all the library functions. Note that:

- all these functions return a QDOS error code but "_oserr" is never set.

- all  the pointers  passed to  the library  functions  as references  to return
  parameters must be initialized (i.e. they must point on an existing variable).

- the string  pointers must point  on a reserved area which size is suitable for
  the returned parameter; e.g. 41 characters for action names, 46 characters for
  filenames  on standard  QDOS/SMS  directory  device  driver  (4 characters for
  possible network prefix  +  5 characters for device name  +  36 characters for
  filename itself  +  1 character for ending 0) - but more room may be needed if
  you are using QVFS -,  up to 32768 characters (yes !) for a command string,  5
  characters for extension names, etc...

a.- fi2_info()
    ~~~~~~~~~~
Prototype: int fi2_info(FI2INFO_t * fi2);

This function will fill  the "fi2" structure  with some sundry information about
FileInfo II.  It returns an error if  either the thing system or the FileInfo II
v3.xx thing is not loaded. Here is the FI2INFO_t definition:

typedef struct FI2INFO {
    char            data_id[6]; /* FileInfo II database Id */
    unsigned short  max_key;    /* Maximum key value allowed */
    unsigned short  bitmap;     /* Bitmap of implemented facilities */
    char *          copyright;  /* Pointer on copyright string */
    } FI2INFO_t;

b.- fi2_call()
    ~~~~~~~~~~
Prototype: int fi2_call(chanid_t con_id, int key, char * filename);

This  is the call  to the FileInfo thing.  See the 'CALL'  extension in 12.6 for
details about the possible values for "con_id" and "key".

The name of the file to process  may be followed  by an additional parameter. In
this case,  the filename  variable  must hold  the name  of the file  to process
(padded with a trailing space if the name length is odd), followed by the string
FI2_PAR_MARKER (defined in fi2_h) and then by the additional parameter. E.g.:

char filename[MAX_FILENAME_LENGTH+1];
char parameter[MAX_PARAMETER_LENGTH+1];
char temp[MAX_FILENAME_LENGTH+MAX_PARAMETER_LENGTH+10]; /* Note that this string
                                                           must be less than
                                                           32767 chars long */
.../...

strcpy(temp, filename);         /* Store the filename */

if (strlen(temp) & 1)           /* If the filename length is odd, pad it */
    strcat(temp, " ");

strcat(temp, FI2_PAR_MARKER);   /* Add the parameter marker (8 chars long) */
strcat(temp, parameter);        /* Add the parameter itself */

fi2_call(-1, -1, temp);         /* Call FileInfo II (no channel, max key) */

c.- fi2_actn()
    ~~~~~~~~~~
Prototype: int fi2_actn(char * filename, short * actions, void ** act_array);

This function is the equivalent of the 'ACTN' extension; it takes a filename and
returns the number of actions associated with it as well as a  pointer on a QDOS
array holding all the possible actions together with their action block address.
This  pointer  is of  generic  type (void *)  because  you should  not use it to
extract anything from this array (use the fi2_parm() function to do so).

d.- fi2_scan()
    ~~~~~~~~~~
Prototype: int fi2_scan(char * ext, short * actions, \
                        char * next_ext, int flag, void ** act_array);

This function is the equivalent  of the 'SCAN' extension;  it takes an extension
name and  returns the number of actions  associated  with it  (regardless of the
calling job name) and the next extension name into the FileInfo II database.  If
"flag" is set to 1,  the function builds  a QDOS array holding  the action names
and their action block address and returns the array address. As for fi2_actn(),
you should use the fi2_parm() functions to extract parameters from this array.

e.- fi2_parm()
    ~~~~~~~~~~
Prototype: int fi2_parm(void * act_array, int param_code, int act_idx, \
                        short * act_type, unsigned short * act_flags, \
                        char * act_param);

This function is the equivalent of the 'PARM' extension;  it is to be used so to
retrieve the parameters associated  with the actions stored  into the QDOS array
built by either fi2_actn() or fi2_scan().  It takes the array address, the para-
meter code  (see the 'PARM' extension in 12.6 for details)  and the action index
(0 to the number of actions returned by fi2_actn() or fi2_scan() less one),  and
it returns the action type, the action special flags and the requested parameter
in act_param C string.

f.- fi2_allp()
    ~~~~~~~~~~
Prototype: int fi2_allp(void * act_array, int act_idx, FI2ACTION_t * act_bloc);

This function returns all the parameters associated with an action (which index
is "act_idx") stored into an array built by either fi2_actn() or fi2_scan().
The  parameters  are  returned  into the  "act_bloc"  structure;  here  is  the
FI2ACTION_t definition:

typedef struct FI2ACTION {
    short           type;       /* Action type */
    unsigned short  flags;      /* Action flags */
    const QLSTR_t * name;       /* Pointer on action name */
    const QLSTR_t * job;        /* Pointer on mandatory/forbidden job name */
    const QLSTR_t * thing;      /* Pointer on associated thing name */
    const QLSTR_t * exec;       /* Pointer on associated executable file name */
    const QLSTR_t * command;    /* Pointer on associated command string */
    void *          address;    /* Absolute address of this action bloc */
    } FI2ACTION_t;

As you can see,  all the strings pointed to  by this structure  are QDOS strings
(QLSTR_t);  they are held  into the  FileInfo II database  and thus must  not be
modified in any way by your program ("const" type).

Note that the "address" field of this structure will not be filled by fi2_allp()
(it is only there for use by the fi2_make() and fi2_link() functions).

g.- fi2_free()
    ~~~~~~~~~~
Prototype: int fi2_free(void * act_array);

This function  (equivalent of  the 'FREE' extension)  is to be  called  once all
the interesting stuff has been retrieved  (using fi2_parm() or fi2_allp())  from
an array  built  by either  fi2_actn()  or fi2_scan().  This will  free both the
memory used by the QDOS array and the "FileInfo II database" thing.

h.- fi2_data()
    ~~~~~~~~~~
Prototype: int fi2_data(void * data_bloc, void ** old_data);

This function is equivalent to the 'DATA' extension;  it may be used to read the
current FileInfo II database address (when "data_bloc" = NULL, the current data-
base address  being returned into "old_data"),  or to set a new database address
(which address is held into "data_bloc", the old database address being returned
into "old_data").

i.- fi2_make()
    ~~~~~~~~~~
Prototype: int fi2_make(char * ext, char * data_id, FI2ACTION_t * act_bloc);

This function is equivalent to the 'MAKE' extension;  it is to be used to make a
new  extension (which  name is held in  "ext" string) or a new action  block (if
NULL  is passed  as "ext").  The  "data_id"  string  should hold  "FIv3" and the
"act_bloc" structure must contain the details about the new action (see above in
paragraph f. for FI2ACTION_t definition).
The address of the new block is returned into "act_bloc.address".

j.- fi2_link()
    ~~~~~~~~~~
Prototype: int fi2_link(char * ext, void * address);

This function  is equivalent  to the 'LINK' extension;  it links a new extension
(if NULL  is passed as "ext")  or a new action  to an existing  extension (which
name is held in the "ext" string). The "address" parameter should be the address
of the  action block  as returned  by fi2_make()  into the  "act_bloc" structure
(act_bloc.address).

k.- fi2_unlk()
    ~~~~~~~~~~
Prototype: int fi2_unlk(char * ext);

This  function  is the  equivalent  of the  'UNLK'  extension;  it  unlinks  the
extension which name is held into the "ext" string.

l.- fi2_load()
    ~~~~~~~~~~
Prototype: int fi2_load(chanid_t data_file, void ** data_bloc, \
                        void ** old_data);

This function  is equivalent  to the 'LOAD' extension;  it loads a file from the
channel which Id is held in "data_file" and, if successful, returns both the new
and the old database addresses.

m.- fi2_save()
    ~~~~~~~~~~
Prototype: int fi2_save(chanid_t dest_file, int save_key);

This function saves FileInfo II code  and/or database to a file which channel Id
is held in "dest_file". See the 'SAVE' extension in 12.6 for possible "save_key"
values.

n.- fi2_hctl()
    ~~~~~~~~~~
Prototype: int fi2_hctl(short * flags);

This function  is equivalent  to the 'HCTL' extension;  see in 12.6 for possible
"flags" values).

o.- fi2_hmax()
    ~~~~~~~~~~
Prototype: int fi2_hmax(short * records);

This function is equivalent to the 'HMAX' extension;  it reads (records = -1) or
sets (to "records" value)  the maximum  number  of records  into the FileInfo II
history.

p.- fi2_hclr()
    ~~~~~~~~~~
Prototype: int fi2_hclr(void);

This function is the equivalent  of the 'HCLR' extension;  it clears the history
of FileInfo II.

q.- fi2_hget()
    ~~~~~~~~~~
Prototype: int fi2_hget(int param_code, short * record_number, \
                        char * record_param);

This function is equivalent to the 'HGET' extension.

- if "param_code" =0, this function returns the number of records present in the
  "FileInfo II history"  into "record_number".  In this case,  you may pass NULL
  instead of "record_param".

- if "param_code" =1,  this function returns into "record_param" the action name
  stored into the record which number is "record_number" (first record is 0).

- if "param_code" =2,  this function  returns  into "record_param"  the filename
  stored into the record which number is "record_number" (first record is 0).

- if "param_code" =3,  this function returns  into "record_param" the additional
  parameter stored into the record which number is "record_number" (first record
  is 0).

r.- fi2_hmnu()
    ~~~~~~~~~~
Prototype: int fi2_hmnu(short * record_number);

This function is the equivalent  of 'HMNU' extension;  it pops up a menu holding
all the FileInfo II history records and wait for one (or "OK" and "ESC" buttons)
to be selected.  It then returns the selected record number into "record_number"
(or -1 for "ESC" and -2 for "OK"). If the history is empty, the function returns
-2 (as if "OK" was selected) into "record_number".

s.- fi2_redo()
    ~~~~~~~~~~
Prototype: int fi2_redo(chanid_t con_id, int key, short record_number);

This function re-does an action  which was recorded (under "record_number") into
the FileInfo II history.  See the 'REDO' extension in 12.6 for details about the
possible values for "key" and "con_id" parameters.

t.- fi2_htdy()
    ~~~~~~~~~~
Prototype: int fi2_htdy(void);

This function is equivalent to the 'HTDY' extension (see 12.6 for what it does).

u.- fi2_thrd()
    ~~~~~~~~~~
Prototype: int fi2_thrd(chanid_t con_id, timeout_t delay, int priority, \
                        char * command_string);

This  function  is the  equivalent  of 'THRD'  extension;  it allows  to use the
"FileInfo II thread"  executable thing  by starting a new FileInfo II thread job
which priority  is "priority".  The "con_id" and "command_string" parameters are
put on the job stack before starting it and the function returns either immedia-
tely (if "delay" is 0) or once the job is completed (if "delay" is -1).
See chapter 9 for details about the "FileInfo II thread" thing command line.


13.- HISTORY OF FILEINFO II:
     ~~~~~~~~~~~~~~~~~~~~~~
FileInfo II is a FileInfo clone (well,  it is now so different from the original
FileInfo that I should say "mutant" instead of "clone"...). It was created first
in 1992 from FileInfo v1.03 to fix some bugs,  to optimise the original code, to
include QD2FI in it and to implement a new "bin" file type (the program name was
FileInfo v1.03mod at that time).

When FileInfo v2.00 was released, I fully reworked the FileInfo v1.03mod code to
upgrade it and add even more features; at that time, as the code was no more the
original one,  and with Wolfgang Lenerz' agreement,  the software  was given the
"FileInfo II" name (FileInfo II v1.x versions).

On the end of 1993 I fully rebuilt  and rewrote the code again  to implement new
concepts.  I then wrote  the "FI2config" program to allow the easy configuration
of FileInfo II  (as I first wrote FileInfo II for my own usage I had no need for
a configurator...). (FileInfo v2.x versions).

On the end of 1996,  I thought about new desirable features and decided to write
FileInfo II v3.00. I finally managed to find time to write it in the second 1997
quarter.

Here is the FileInfo II v3.xx changes record:

v3.00 : first release.

v3.01 : a bug corrected that prevented  FileInfo II  to initialise under QDOS or
        Minerva. FI2config also failed under QDOS (fixed in FI2config v2.01).

v3.02 : two more bugs corrected  that prevented  to configure FileInfo II  under
        QDOS (again a different register usage between QDOS/Minerva/SMSQ...).

v3.10 : - The "S*BASIC commands"  action type  now also works  when the job 0 is
          asleep (buttonized as "System asleep").
        - The FileInfo II  "view file" thread  is now the child of job 0 so that
          it does not disappear if the calling job terminates.
        - The action selection menu now got a selection keystroke for each item.
        - The "FileInfo II history"  thing has been implemented  and the related
          FileInfo II extensions and S*BASIC PROC/FN have been added.
        - The new  the "FileInfo II thread" thing  allows to call FileInfo II as
          an executable thing (it also supports events and history handling).
        - The "FileInfo2_bin" file  is now configurable using (Menu)config:  the
          configurable items  are the QPAC 2  "system asleep"  button name,  the
          history  parameters,  the menu titles  and colors,  and the menu items
          selection method.
        - Many improvements to the documentation.
        - "del_obj" utility and its sources added to the distribution.

v3.20 : - A bug corrected in 'HMNU' extension that could crash 68008/68000 based
          computers (address error due to a miss aligned word).
        - A bug corrected in 'LOAD'  extension (memory was allocated to the cal-
          ling job instead of job 0 when no address was imposed for loading).
        - A bug corrected  in 'ACTN' extension  where the "FileInfo II database"
          was not freed when an error occured.
        - 'HMNU' now returns -2 as the selected item ("OK") instead of reporting
          a "not found" error when the history is empty.
        - FileInfo II  ""  and  ""  special  symbols  made aware  of networked
          devices  (e.g.  "n15_win3_"  or  "s2_flp1_")  and  are  therefore  now
          replaced with sensible strings in command lines for these devices.
        - FileInfo II made QVFS naming conventions aware.
        - A work around implemented for QVFS (v0.06 and earlier) bug in iof.rhdr
          trap.  This work around  makes FileInfo II "waste" 448 bytes of memory
          (not a big deal huh ?) and thus will be removed  in future FileInfo II
          releases when QVFS bug is fixed.
        - FI2_SAVE procedure is reasserted each time a new FileInfo2_bin file is
          LRESPRed in memory (work around for a QDOS bug in which the previously
          loaded procedure  gets precedence  over the freshly loaded one);  this
          prevents  saving by mistake  the old  FileInfo II  code instead of the
          newly loaded one when upgrading.
        - 'HTDY' extension and "FI2_HTDY" S*BASIC procedure added.
        - "-H" option added to the "FileInfo II thread" thing.  As a result, the
          command line options are now case-sensitive.
        - Menu items justification made configurable (with (menu)config).
        - A C68 library  added  to  the  FileInfo II  distribution:  its name is
          "libfi2_a" and it allows to use  all the FileInfo II features from C68
          compiled programs. Sources are also provided for example purpose.
        - "copy_obj" utility and its sources added to the distribution.

v3.30 : - A bug corrected  into "FileInfo II thread"  thing which could report a
          "bad  parameter"  error to the  calling  job  when no "-e" option  was
          specified.
        - "-s" option added to the "FileInfo II thread" thing.
        - 'THRD' extension and associated  FI2_THRD/FI2_FTHRD PROCedure/FuNction
          added.
        - fi2_thrd() C68 library function changed  to take the new 'THRD' exten-
          sion into account (libfi2_a version is now 1.10).
        - All S*BASIC PROC/FN are now actually using (SMS.UTHG) the "FileInfo II
          extension" thing instead of doing direct branch to internal code: this
          guarantees that the most up to date  loaded extension is actually used
          (was not the case before when multiple FileInfo2_bin files were loaded
          in a QDOS system; SMS* was OK in this respect) and that when the thing
          is removed, the S*BASIC PROC/FN cannot be used any more.
        - FileInfo II S*BASIC PROCedures/FuNctions now accept filenames of up to
          32767 characters (were limited to 41 characters before). Of course for
          names longer than 127 characters, you will have to use quotes (because
          the QDOS/SMS name table only allows for 127 characters names). This is
          useful when using QVFS.

v3.31 : - A bug corrected  that was affecting  all S*BASIC  procedures/functions
          accepting a channel parameter; this bug made them to return wrongly an
          "invalid channel Id"  error  when used  from  a compiled  S*BASIC  job
          without an open channel #0.
        - A bug (introduced in v3.30) corrected that was preventing "FileInfo II
          thread" to work when invoked with the "-w" option.
        - "fi2_h" changed ("const" in the FI2ACTION_t structure).

v3.40 : - When presenting the "Actions" menu,  FileInfo II may now remind you on
          what "file to process"  these actions  are to be applied (configurable
          with (Menu)config).
        - Additional parameter feature implemented  as well as the corresponding
          changes to the history, FileInfo II extensions,  S*BASIC PROCs/FNs and
          fi2_call() library function (libfi2_a is now v1.20).
        - A bug corrected where  commands line  to be stuffed  into the keyboard
          queue was not sent  if the "wait for  end of processing job"  flag was
          set (or forced via the bit 31 of the key).

v3.41 : - A bug corrected into the additional parameter handling.
        - Distribution change:  added Wolfgang Lenerz'  FileInfo II installation
          program into the "util_WL_" directory of the FileInfo II archive.


14.- HINTS AND TIPS:
     ~~~~~~~~~~~~~~
Here are some hints about how to use FileInfo II at best:

14.1.- Using FileInfo II history:
       ~~~~~~~~~~~~~~~~~~~~~~~~~
You may assign a hotkey  and a QPAC 2 button  so to make the FileInfo II history
menu  to pop up.  The  easiest  way for doing this  is to use  the  "FileInfo II
thread" executable  thing.  Adding the following lines  into your boot file will
do the trick:

REMark <ALT h> will pop up the menu of FileInfo II history
ERT HOT_WAKE("h","FileInfo II thread";"-h")
:
REMark and <ALT H> will tidy up the history before poping up the menu
ERT HOT_WAKE("H","FileInfo II thread";"-H")
:
REMark set up a QPAC 2 button for <ALT h>
BT_HOTKEY "h","FileInfo II"

Please note that the  history menu will only be presented to you  if you got the
JMS Menu extensions and when history is not empty.

14.2.- The good usage of the "joker" extension:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The "joker" extension holds  default actions  for files without  an extension or
with an extension which  is not recognized by FileInfo II.  Such default actions
may be common  to all programs invoking FileInfo II  and some others may be made
dedicated to a specific program.

Example 1: for  use with "ACP", add  an "Execute" action to  the joker extension
           and give "ACP"  as the "Mandatory" job name (the  "Mandatory" item in
           FI2config menu must therefore be  selected). This action will only be
           executed or proposed  to you when ACP invokes FileInfo  II passing it
           the  name of  an executable  file without  extension or  with unknown
           extension.

Example 2: adding  a delete file capability  to "ACP" is  easy.  Add  a "Delete"
           action to the  joker extension with "ACP" as the  mandatory job name,
           "del_obj" as the  "executable file to load"  and "<devN_name_ext>" as
           the command  line (to be  put on the stack).  You may of  course also
           want to add the same action to all other extensions so that ACP could
           propose  you to  delete any  files  (i.e. including  the files  which
           extension is recognized by FileInfo II).

Example 3: PWfile  and FileInfo II.  The PWfile documentation  recommends you to
           amend the  original FileInfo II  configuration by deleting  the "ACP"
           mandatory job name  for the "Execute" action of  the joker extension.
           THIS IS  THE WRONG WAY TO  DO THE RIGHT  THINGS.  If you do  so, then
           QPAC 2, DM5 and  every other programs using FileInfo II  will no more
           be able to  execute files themselves (i.e. with  their own algorithm)
           because FileInfo II will report that it got a matching action for the
           file they are about to execute; QPAC 2 or DM5 will therefore pass the
           control to  FileInfo II (this of  course will work but,  for example,
           you will not be able to use QPAC 2 detailed menu with unlock, freeze,
           guardian window and  Psion options). Instead, you  should add another
           "Execute" action to the joker extension  with "PWfile" as the "manda-
           tory job name".

14.3.- Writing utilities for use with FileInfo II:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When a software uses FileInfo II, it can easily be "extended" so to execute file
operations for which it was not designed for.

As an example,  you will find  the small "copy_obj"  and "del_obj"  utilities in
this package.  They were designed so that ACP could copy,  move and delete files
which names  are held  in its right window  (the window which  holds the current
directory file list).  Normally,  issuing a DO event on one of these names makes
ACP  to  invoke  FileInfo  II.  With  the  help  of  "copy_obj",  "del_obj"  and
FileInfo II,  we can  then make  ACP to propose  you to  copy/move or delete the
file or  to take the  other actions already  defined for  this file type  in the
FileInfo II data base. Have a look to the original "FileInfo2_bin" configuration
for  the  "Copier/Dplacer"  and  "Dtruire"  (french words  for "Copy/Move" and
"Delete") actions associated with each extension...
You will also find the "add2zip_obj" utility that can be used as an interface to
InfoZip so to add files  to a zip file  via FileInfo II  (look for "Ajouter  un
fichier Zip" actions into the original "FileInfo2_bin" data).

The  sources for  "copy_obj",  "del_obj"  and "add2zip_obj"  are  joined to  the
distribution  so  you can  see  how  to write  your  own  utilities. The  system
requirements for these utilities are PTR_GEN+WMAN+HOT_REXT+QMenu+Toolkit II.

Another type  of utility you may  want to write is  a "wrapper". A wrapper  is a
small program  that will be used  so to setup  the context for the  main program
that it will also launch.  Example:  I was  asked by a user if I could implement
some facility  into FileInfo II so  to setup  the DATA_USE  and PROG_USE  before
launching the program responsible for the file processing.  Beside the fact that
setting  DATA_USE and  PROG_USE  in  this way  would  not  be very  multitasking
friendly, this  would have  made the  FileInfo II  configuration harder  for the
average user.  I then decided not to implement this, but nothing prevents you to
write a wrapper for such a case. Here is how to do this:

100 C$=CMD$:REMark Get the command line passed by FileInfo II
110 PROG_USE "win1_MyProgDirectory_":REMark Set the PROG_USE
120 EX "win1_MyProgDirectory_MyProg_exe";C$:REMark Start the program

Once QLiberated,  this wrapper (let's call it "MyProgWrapper_obj")  will have to
be called by FileInfo II instead of  "MyProg_exe". You will then have to replace
"win1_MyProgDirectory_MyProg_exe"  with "win1_MyProgDirectory_MyProgWrapper_obj"
into the "Executable file  to load" window of FI2config.  Of course you may want
to do more  complicated processing within the wrapper  before calling MyProg_exe
(for example  by extracting the  directory from the  "file to process"  which is
stored in C$,  and then set DATA_USE accordingly;  there is an example of such a
directory and file names extraction routine into the "copy_sbas" file).

14.4.- Using FileInfo II with some FileInfo unaware programs:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some programs,  are stuffing the name of files they just  loaded/processed/saved
into the hotkey buffer (in fact if a program uses the QMenu file selector,  then
the filename WILL be stuffed into the buffer)  for a later recall with ALT+SPACE
keys.
The good news  is that you may use FileInfo II  with such programs  even if they
are not FileInfo aware !  To do this, just define a hotkey, e.g.:

REMark <ALT s> will call FileInfo II with the stuffer buffer contents as the
REMark         "file to process" argument.
ERT HOT_THING("s","FileInfo II thread";"-s")

Now,  pressing <ALT s> will make a FileInfo II "Actions" menu to pop up (if more
than one action  is possible,  else the only possible action will be immediately
executed),  corresponding to the file to process name which is currently held in
the stuffer buffer... ;-)

14.5.- FileInfo II friendly installation of your own software:
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are yourself writing software than can make use or benefit of FileInfo II
then  why not  include  a FileInfo  II  database update  routine  into your  own
installation utility for this software ?  Wolfgang Lenerz wrote a set of S*BASIC
routines that  may be used  to achieve such  a goal. Please  have a look  to the
"util_WL_" directory of the FileInfo II  distribution archive (the files in this
directory are (c)2000 Wolfgang Lenerz, please  read the copyright notice held in
the "fi2inst_txt" file).


15.- THANKS !
     ~~~~~~~~
I would like to thank Wolfgang Lenerz for the amendments he made to the FileInfo
specifications on my request,  as well as for allowing me to extend the original
specifications (this was needed for FileInfo II v3.xx).

I would like  to thank  as well  all of those who,  by their suggestions  and/or
their support,  helped me to improve FileInfo II and particularly among them (in
alphabetical order):

      - Jean-Louis Dianoux,
      - Albin Hessler (for adding FileInfo support in Cueshell),
      - Peter Jaeger,
      - Jochen Merz (for extending scrap extensions so to store >32Kb pictures),
      - Ralf Rekoendt,
      - Davide Santachiara,
      - Tony Tebby (for QDOS/SMS, PE, QPac II, etc...),
      - Roy Wood.


Up to date on August the 13th, 2000.                           Thierry Godefroy.
