QLIBJN
                                 ======

         Alter the name of a Q-Liberator compiled job on the fly


QLIBJN (formerly QLIBJBN), sets the name of any SBASIC daughter job or
job compiled with Q-Liberator, Turbo (or MBASIC?), while the job is
running.

Usage:

        QLIBJN 'My little job'


New in this version (0.04): The command does not error if the name you
provide is longer than permitted. It simply trims the name to the defined
length.


Variable Job names
------------------

Job names are usually not an issue. Choose a nice, terse name for your job
at compile time that identifies it from other jobs and that gives some
inkling of what it is or does. Perhaps append a version number,.. Thats
it! No big deal; you dont need QLIBJN.

However, the job name can also be used to provide variable information.
See for example Qpac2 Files: The job name tells you what mode the job is
in: Files, View, Copy, etc; and its current working directory. This may be
useful if you have many instances running, some, perhaps, burried under
other windows, and you want to pick the one you need, for example, from
the Jobs menu without having to cycle through all the jobs currently
running. There are, hwever, many other things you can use variable job
names for: Inter-job communication, grouping, etc. I explore some of these
possiblities in some of my utility programs, such as QuickView (QV).

QLIBJN makes it possible to use variable names in Q-Liberated jobs,
although it is somewhat limited due to a fixed, arbitrary length
restriction set by Q-Liberator that was thought sufficient at the time of
its inception.

To display a full directory name safely you need room for about 40
characters for the directory and some to spare for the job name. Hence in
SMSQ/E 48 characters are recommended for the job name allowance.

Below is a summary of name length restrictions in various types of jobs.


Job name Lengths
----------------

Current versions of QLib, ie V3.35 and V3.36, only allow a job name of
maximum 22 characters (other versions may have lower limits!) As it
stands, QLIBJN will truncate the supplied name to 22 characters wherever
it is used (Qlib, SBASIC, Turbo,..)

Turbo allows for slightly longer job names than Qlib, 36 chars, I believe.
However, different versions have different limits, so I havent made a
Turbo version of QLIBJN.

SBASIC in SMSQ/E up to at least V3.35 allows a limit of 40 characters. You
can of course use QLIBJN as it stands, but this restricts you to its
in-built 22 character limit. For programs that arent to be compiled you
may just as well use the built-in command JOB_NAME. JOB_NAME only works
for SBASIC daughter jobs, not compiled jobs.

Most executable programs can be set up as executable Things using one of
the HOT_xxx commands. This creates a new job header with room for the job
name to be up to 48 characters!

This also applies to Q-Liberated and (presumably) Turbo-compiled tasks.
However, this will ONLY work while the program is executed as a Thing. The
same program will be constrained to the limits outlined when EXecuted in
the normal way, so beware!

If you wish to use this command for a specific project, where such details
are known, simply change the mxjn EQUate in qlibjn_asm and re-assemble.
QLIBJN will happily change the job name of a Thing or any job with the
limits you set.

NOTE: You will crash your system if you use QLIBJN to enter a name longer
than the limit for a given type of job!


NEW!
----

Martin Head has created a program to expand a Q-Liberated job's header
to allow for longer job names. I include the program with this toolkit. If
you apply the patch you can use the pre-assembled toolkit QLIBJN48_bin to
add names of up to 48 char on the fly to your program. Or alter the limit
in qlibjn_asm, and add it to some bespoke toolkit for that job.

To stretch a Qlib job load Patch48_bas and supply your program's file- and
job name, then:

        ERT Patch48(<filename>, <jobname>)

Note! It is not Q-Liberator itself that is to be patched but your
Q-Liberator compiled program!

Patch48 is an SBASIC program, although its product should run anywhere it
ran before (Qdos, Minerva, SMSQ/E).

Patch48 is a hack! Ie, the are anomalies. For example if your Qlib program
crashes, it will display the name given when compiled in its error
console, not the new name or any name later set with QLIBJN48.

Note: Patch48 has not yet been extensively tested in the wild. Use at own
risk! Please report any problems to me! Contact information at Knoware.no


Software Status
---------------

If you use this code in your own published programs, an acknowledgement
would be the polite thing to do..

Patch48_bas is by Martin Head, packaged by pjw.

QLIBJN:

V0.01 .. V0.03, pjw, 2oo4 Nov 29 .. January 17th 2oi9
V0.04, pjw, 2020 Apr 06, truncate instead of error


Conditions and DISCLAIMER as per Knoware.no