The QL Toolbox '98 Collection
-----------------------------

ListNames - Discover what's in a Resident Extension File
--------------------------------------------------------

Introduction
------------
ListNames is a Pointer Environment utility for scanning Resident Extension
files (_Rext, _bin, _cde etc.) and listing the names that are defined
within the file. It does this first by analysing the code and searching
for a recognised call to the QDOS bp.init vector (sb.inipr in SMSQ), and
then by interpreting the data held at the address passed to this vector.
If the program cannot reliably identify a call to bp.init (there are some
quite devious extension files out there), it will try a secondary pattern-
match scan of the file to try and find a sequence of data that obeys the
basic rules for a list of names.

By whatever route ListNames identifies the table, the program will display
some information about the file, and will then list the procedure and
function names, and their relative start address within the file. Function
names are distinguished from procedures by suffixing them with a pair of
brackets.

Note: This program requires both Jochen Merz's excellent Menu Extension, and
QJump's Toolkit II to be present.

Instructions
------------

There are two versions of the executable, both of them have the QJump
Pointer Toolkit bound to them, so this does not need to be resident
(Although, of course, the Pointer Environment or SMSQ must actually
be there!)

In addition, ListNamesRT_obj has the QLiberator Runtimes bound as well.

User Interface
--------------

The program presents a fairly standard user interface.

There are three data items, two options, and a List button to start the
process off.

The User Interface for this program is, I hope, fairly standard.

A DO on the title to the left of a field will call up File selection
box, if appropriate, otherwise it will enable you to directly edit
the field contents.

A DO on the field itself, will have the same effect.

A HIT on a field enables you to directly edit the field contents.

Whilst editing a field, most of the standard QDOS editing keys work
as expected. But there are some additional keys which are worth knowing
about:-

[SHIFT]+[SPACE] (Normally the [INSERT] key on a PC keyboard) toggles between
insert and overwrite modes.

[CTRL]+[S] will insert the contents of the scrap at the current cursor
position. Be careful with this, the Scrap can hold a LOT of data!

[CTRL]+[SHIFT]+[S] puts the current contents of the edit buffer into the
Scrap, overwriting anything already there.

[CTRL]+[SHIFT]+[H] puts the current contents of the edit buffer into the
HotKey System II Stuffer Buffer.

[CTRL]+[SHIFT]+[F] calls up the Menu Extension's Character Select dialog,
allowing you to select any character to insert at the current cursor
position.

Screen Items
------------

The items on the screen are as follows ...

Source: The name of the file that you want to examine.

Target: The optional name of a file that you want the output to be sent
to. This can be useful if you are creating documentation or just if you
want a permanent record.

Offset: If you want, you can tell ListNames the start address, in the
file, where the list of names is stored (i.e. the address that you LEA
prior to a call to bp.init).
Normally you can leave this field alone, because ...

Auto: If Auto is selected (the default), then ListNames will automatically
scan any source file that you select and attempt to calculate the offset
for you. If ListNames has to go to a second pass, or the file is large,
the search progress will be shown in the area normally reserved for the
List button to show you what is happening.

To Scrap: If selected, all output will be sent to the Scrap (the Target
field will show <SCRAP> in this case). This is handy for pasting into
'Scrap-friendly' editors, like QD.

Move, Quit: These function as normal for a Pointer Environment program.

Info: Displays the obligatory program version and credits. Also called up
by the [F1] key.

Zzz: Clicking this will minimise the program to a button positioned,
by default, in QPAC 2's Button Frame (if it is present). Sleeping the
program will lose the contents of the output window.

List: This is the big button above the output window. It will only be
enabled if a List can actually be produced. Click it to either display
the list of procedures/functions in the output window, or send it to the
selected target file.

Command Line
------------

Parameters may be passed to the program via the command line using the
EX, EW, QX, QW etc. commands. ListNames recognises a command line in the
following format:-

  SourceFileName TargetFileName Offset

All three parameters are optional, but you cannot skip a parameter (so
you cannot specify just a Source File and an Offset, the Target File
must also be given).

TargetFileName can be CON (the default), in which case all output is
sent to the program's output window.

In addition, you can include switches anywhere in the command line:-

  /X  Execute immediately and then go away.

  /B  If supplied, then /X must also be supplied. This combination will
      cause the program to execute entirely in the background. No window
      will be displayed, and no dialog boxes will appear. Any confirmation
      requests will be taken as YES.

  /W  If combination with /X, causes the program to pause on completion
      and display a message box to confirm processing has completed, and
      to indicate where the output was sent.

  /S  Sends output to the Scrap.

  /0  Ignore any channels that have been passed (see note below).
      This facility is only useful in cases where the program has
      been launched by a shell that automatically sets up the three
      channels stdin, stdout and stderr.

There is one special case when using the /X switch. If the Target has
been specified as CON in the command line, the program will pause with
a 'Processing Complete' message, to enable you to read the output, before
exiting.

Examples:-

  EX 'ListNames';'WIN1_EXT_Something_Rext /x /s'

  Send name information about WIN1_EXT_Something_Rext to the Scrap, then
  exit at once.

  EX 'ListNames';'WIN1_EXT_BarkingMad_Rext RAM1_WoofWoof_txt 10'

  Load ListNames and preset all three fields to the values supplied, and
  then wait for the user to start the processing.

You can also pass a channel to ListNames using the EX or QX commands. If
supplied, this will be used as the channel to which the information is
sent. In these circumstances, the "To Scrap" option will be disabled, and
the Target filename cannot be edited - containing, instead, the Long Word
ID of the supplied channel.

  OPEN_OVER #3,'RAM1_LotsOfNames_txt'
  EX 'ListNames_obj',#3;'WIN1_EXT_Array_Rext /x'
  EX 'ListNames_obj',#3;'WIN1_EXT_AtariDOS_Rext /x'
  CLOSE #3

The example above shows how this technique can be used concatenate the
information produced from multiple files.

If three channels are passed, these are taken to be stdin, stdout and
stderr, and the program assumes that it has been launched from a UNIX-like
shell and should act as if it were a simple command-line utility. In
these circumstances, the /X and /B switches are automatically forced on.

Configuration
-------------

There are two defaults that may be configured using the standard Level 1
or Level 2 Config Program: The default directory where extension files
are normally stored, and the extension that you normally use for these
files.

The Configuration information was added to the program using Oliver Fink's
BasConfig utility.

Compatibility
-------------

This version of the program has been tested under SMSQ 2.85 and Minerva
1.97 - it should work under other QDOS clones/variants but I offer no
guarantees.

Revision History
----------------
0.21q   31/01/1998      First version to make it to the "Outside World"
0.25    01/02/1998      1) User-Interface slightly tidied up so that fields
                        can be hit for alteration.
                        2) Program internal structure tidied.
                        3) No longer needs QPAC2's Button_Sleep Thing.
                        4) Fixed bug that 'forgot' the name of the current
                        file if an [ESC] was used to exit the File
                        Select dialog.
                        5) Fixed the problems that caused the program to
                        crash if (undocumented) information was passed
                        to it in the command line.
0.30    07/02/1998      Allowed HITs on fields to directly edit
                        their contents
0.31    11/02/1998      Fixed bug with [DEL] key when editing
                        a field
0.40    17/02/1998      Added support for passing a channel.
0.45    23/02/1998      Added support for /B switch.
0.50    01/03/1998      Copes with multiple channels passed
                        (i.e. stdin, stdout, and stderr)


License Terms
-------------

You are granted a license to use and distribute this software. The
terms of this license are stated below.

Provided that credit is given to the author, and that such credit is
included in any accompanying documentation, whether it be on written
or electronic media ...

1) This program may be freely distributed.

2) This program and its documentation may be incorporated as part of
another package, so long as it does not form the major or substantial
part of such package, and so long as, when taken in combination with
other programs supplied by the author under the same terms, the programs
together do not form the major or substantial part of that package.

3) The executable(s) may be modified, or patched, as necessary, to suit
different target environments. However, where such alterations are made,
and the executables are distributed, details of these changes must also
be included in electronic or written form.

No charge may be made for this program, other than reasonable costs of
electronic media and data transmission to facilitate its distribution.

The author gives no warranty as to the suitability of the program, or
the accuracy of the documentation. The programs are supplied 'as-is'.
It is the responsibility of the user to establish whether the program
is suitable and safe to use in his/her environment.

The author accepts no responsibility for any data that is lost or
corrupted as a result of using this program.

The author will make his best endeavours to fix any problems that are
reported to him, but does not accept an obligation to do so. The author
may be contacted via the E-Mail address quoted at the foot of this
document.


Adrian Ives
ADIves@aol.com
01/03/1998
