FI2Call
                                 =======


These are a few "skeleton" routines to invoke a FileInfo2 (FI2) call menu.
By skeleton I mean that they are meant to be altered to your specific
needs; they arent complete, Black Box, functions.


Requirements
============

FileInfo2 must be loaded and active.

For simplicity of demonstration these routines were designed using JMS'es
Qmenu. In practice you might just as well use EasyPtr, Qptr, or even some
self-devised menuing system instead.


Limitations
===========

This is only a simple implementation. It doesn't cater for the full
panoply of FI2 capabilities. Most people (I presume) will only have done
simple configurations of their FI2 system, without too much messing around
with the more esoteric features available. They should be fully covered
here! Those who have spent time and effort devising sophisticated setups
will also, no doubt, have the wherewithal to improve on this suit
themselves - or devise their own!

Note: One important routine is missing! Namely the one to interpret an FI2
call and carry out the action. This may be added later.


Background
==========

Say you have written a program that would like to offer an FI2 function,
you could just use something like

        er = FI2_FCALL(filename$)

Then, if only one relevant action were available for the file type, a
suitable program would execute acting on that file. If more than one action
were defined, a menu would appear allowing the user to chose between a
selection of actions. The file would then be opened in the appropriate
program for that action.

In the latter case, one of my biggest gripes, not only as a programmer,
but as a user, is that that little menu reserves the whole of the screen
to itself! Of course it is nice to be able to move such a menu across the
whole screen, but in most cases this is unnecessary. Moving it within the
limits of the calling program's outline should be fine! that's how most
menus are supposed to work after all.

Another problem is that your program may have local functions that are not
necessarily something you want to add to the full FI2 database. You CAN
define them to only become visible in your specific program, but it would
be asking a lot of the user to fiddle out how to do that using the FI2
Configurator. Another thing is that the list of actions might also vary
depending on conditions internal to your program, and THAT cannot easily be
specified in the FI2 database, if at all.

In sum: You should be able to create your own FI2 menu in accordance with
your own needs if you want. And this is what these routines are in
aid of.


Usage
=====

FI2Call
-------

This routine takes two parameters: <file name> - the name of the data file
you wish to "execute", and an extra <string array> parameter that contains
the texts of any additional actions you may wish to add to the menu.

These extra actions need not have anything to do with the data file in
question! They could relate to some other function of your program and be
there simply to avoid having two subsequent menus being called up.

FI2Call first checks whether the data file exists and returns an error if
there is a problem.

The same variable, noa%, is used again for its real purpose: to record the
number of FI2 actions associated with the file.

The routine then goes through all the associated actions to determine the
width the menu needs to be.

Finally it calls FI2menu, a subroutine, which actually creates and
displays the menu.


FI2menu
-------

This routine is merely a sub routine, only meant to be called by FI2Call,
and not directly.

The way it is structured is that it puts the extra actions in front/on top
of the FI2 actions. You could easily change that to putting them below.

The menu is created in a LOCal array, ie it vanishes and releases its
memory once a menu selection has been made and the routine returns.

Here also, it uses Qmenu's LIST_SELECT routine for simplicity's sake. You
could just as well use an EasyMenu menu here.


FI2acts
-------

Once the user has made their selection from the menu displayed by FI2menu
the action associated with that choice must be carried out. that's what
FI2acts is for.

Based on the action chosen it returns all relevant information associated
with that action, the Thing name (if any), the program file name (if any),
the command line (if any), and so on. (What they all mean you can find in
the FileInfo2_txt manual that comes with FI2.)

These are all found in a set of GLOBal variables called fi_xxx$. You can
then use this information to perform the requisite FI2 action. It is not the final
step, as this information still needs to be parsed and processed before the call
can be made. However, these functions may be added later once I've finished
writing them in a generalised way.

The extra actions, defined by you, the programmer, are not covered. These
you must define yourself.


Harness
-------

The top few lines < 100 are a minimalist test harness for a simple
demonstration:

The data file chosen is the S*BASIC demo file itself, so the actions
available are based on the "bas" extension.

Three extra actions are added to the action menu, 0..2. These are
Test1..Test3

The FI2Call is made with these parameters and the chosen action number
returned. The action number, action%, is the number of ALL actions
defined, not only FI2's.

Finally, the action number is converted to the real action number by
FI2acts, and the relevant information returned to be acted upon.

It should have been possible, based on the returned action number, ie
(action% - xt%), to call that action directly using an FI2 command, but
sadly, such a command is missing! Only if the action you want happens to
be the first, can this be done. In all other cases you either have to put
up with the original mickymouse menu, or you have to emulate that whole
mechanism yourself in BASIC!

I've written to the FI2 author explaining the matter and politely
asked whether theyd consider making an update. But so far they havent
deigned even to acknowledge receipt!


Software status
===============

FileInfo2 is © 1993-2005 Thierry Godefroy, adapted from the original
Wolfgang Lenerz' FileInfo thing.


These routines are

V0.01, pjw, 2022 Jan 09

Conditions and DISCALIMER as per Knoware.no