QL Software
PickQD
======
Manage multiple copies of QD
About PickQD
New in this version
Requirements
Note and Beware
Getting started
Configuration
In use
Troubleshooting
Program Notes
Software status
About PickQD
============
You may have experienced that you have so many copies of QD running that
you cant (quickly) find the one you want. So it would perhaps be nice to
have a list of which ones are running so you can pick that to the top of
the pile without having to cycle through the whole lot. Or perhaps its
better to button them out of the way - or just shut the whole lot down?
PickQD could be the solutions to your problem!
When invoked, PickQD presents a menu with five commands:
0 - New QD -
1 - Buttonise QDs -
2 - Unbutton QDs -
3 - ShutDown No Save -
4 - ShutDown & Save -
5..N - List of running QDs
Click on items 0 to 4 to act on all running instances, or click on the QD
you want to pick that to the top of the pile.
New in this version
===================
Take note: If you are updating from a previous version by unzipping over
the old installation files your PickQD_cfg configuration file could get
overwritten!
Your old PickQD_cfg configuration file (if any) needs to be updated! You
need to add the line
FSEL
at the top of the file or, if you don't use Fsel as a Thing, add a blank
line to the top of the configuration file. See Configuration, below, for
details
Requirements
============
PickQD requires JMS'es Qmenu to run. It also requires SMSQ/E V3.36 or later
(for the FDEL and SUSJB commands). You may be able to use earlier versions
of SMSQ/E with the addition of one or more of my "compatibility toolkits",
available at Knoware.no
FSEL, the floating FILE_SELECT$ wrapper is also required and is included
with this package. The compiled version, PickQD_obj, needs Qlib_run or
equivalent. If you decide to use PickQD uncompiled (not recommended except
for testing or development) you need to load the included toolkit
PickQD_bin.
Since PickQD originated on Qdos, it shouldnt be too hard to re-engineer it
for Qdos again - the source code is included! However, please don't grumble
if PickQD doesn't work very well on current "QL" hardware in high colour
mode. These systems are just too slow to do it justice. In QL colour mode,
it may still be acceptable, though.
* * * * * * * * * * * * * * * NOTE and BEWARE! * * * * * * * * * * * * *
* *
* PickQD works by stuffing the keyboard queue with the characters you *
* would normally type at the keyboard. However, it does this *
* automatically with very little awareness of the effect of its *
* actions. So, it could, potentially get in a muddle, especially if *
* there are other things going on in the machine - like you moving your *
* mouse rapidly around while PickQD is working - or even activities of *
* the host platform in the case of emulators. This could cause a *
* problem particularly with the Save and Shutdown option! *
* *
* Another danger with unsupervised saving is that one may inadvertently *
* have entered spurious characters into a file and these get saved *
* without one noticing. They can be hard to find later - unless *
* something goes wrong! *
* *
* PickQD started life as a "quick hack". However, I have spent some time *
* recently to try to make it more safe. Options 0 to 3 are pretty safe. *
* Option 4 - Save and Shutdown is by its very nature inherently *
* "unsafe". *
* *
* Also I have not been able to test every possible combination of *
* actions or environments a user might subject it to. The decision to *
* Use or not to Use is entirely yours - as are the consequences. *
* *
* You could, of course try to improve PickQD: you have the source code! *
* (And then Id like to have a copy!) *
* *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Getting started
===============
PickQD expects QD to be loaded as a Thing. You do that by, for example,
doing a
LRESPR <path>QD
in your boot file and then adding the Hotkeys you require to invoke or pick
QD.
FSEL can optionally be loaded as a Thing in your boot file, eg do a
ERT HOT_RES1("F", '<path>FSEL_obj'; '/P2', 'FSEL')
PickQD could be invoked with:
EX <path>PickQD_obj[ ; <alt home directory> ]
however, it is designed to be invoked via a Hotkey.
I use the following Hotkey set for QD and PickQD. You can, of course, use
key combinations of your own choice:
cml$ = '\dwin1_prg_ \e_bas \h<path>bas_ \tQBasic \c100 \n68'
ERT HOT_THING(CHR$(17), 'QD'; cml$
ERT HOT_WAKE(";", 'QD')
..
ERT HOT_RES1(':', "<path>PickQD_obj"; 'dev2_', 'PickQD')
where <path> is some location, not necessarily the same one. CHR$(17) is
CTRL + ';'
Additionally, after the above, you could put PickQD on a button:
BT_HOTKEY 'PickQD','PickQD',,, 1
Just click on the button to invoke PickQD.
Note: Control characters don't work well on SMSQmulator, so the CHR$(17)
line only works for QPC2, Q68, Qx0, etc. However, there are so many
different other ways to start QD that I hadnt noticed for many years!
What this means is that ALT + ';' cycles through all the different
instances of QD running on the machine, while ALT + SHIFT + ';' fires up
PickQD to manage them. ALT + CTRL + ';' starts an instance of QD ready for
writing a BASIC program. Among other things (see the QD manual!) it tells
QD where to find the BASIC help files, and it configures QD to use the
QBasic Thing. (On SMSQ/E I now much prefer to use the SBAS/QD Thing.)
The reason I use dev2_ as the location for the PickQD configuration file is
that dev2_ points to a different place on each platform, so each platform
can have a different configuration file best tuned to its capabilities.
That also means that I can use identical disks on each platform and not
have to fiddle with maintaining separate backups, boot files, etc, for
each: Whichever platform Im working on, its always my "Home QL".
Configuration
-------------
There is a small and primitive configuration file that needs to be attended
to first. Its called PickQD_cfg. Its a plain text file consisting of a few
entries, each on their own line. The location of this file is expected to
be found in the Home Directory. However, if a different location is
provided on the command line, then this is used instead. In fact, if you
load PickQD as a Thing, the location of the PickQD_cfg file HAS to be
supplied on the command line as Hot Things don't know about the Home
Directory yet.
Note that if the file cant be found youll get a Not Found error dialog as
the first thing when you try to start PickQD.
Heres a sample config file. Everything behind and including | is comment
for the purposes of illustration. No comments are allowed in the actual
file:
FSEL | FSEL Thing name - or no name
win1_util_file_Fsel_obj | Fsel_obj or <path>Fsel_obj
10 | Breathers in 1/50th second
asleep | Sleep thing job name appendix
QD NO NAME | Unsaved QD document name
QD row/column | QD help job name
* \n80 \c80 | Fallback command line for QD
txt \n80 \c80 | Text file command line for QD
bas \n80 \c100 \hwin2_hlp_bas_ \tSBAS/QD | Basic source file command line
asm \n80 \c100 \hwin2_hlp_asm_ | Assembler command line for QD
Here is the nitty-gritty:
1. If you have chosen different name for the FSEL Thing, enter that here.
The default name is FSEL. If you leave this line blank, no attempt will
be made to use the FSEL Thing and the program name you set below will
be used instead.
2. On line 2 supply the full name and location of the FSEL utility. If only
the text 'Fsel_obj' is entered then the current (Home) directory is
used. FSEL needs to be V10 or later. (Included with the package.) If
youve loaded FSEL as a Thing, this information is ignored, as PickQD
will try the FSEL Thing first.
3. The timeout delay. You may need to try out different values here
depending on your system. Values between 5 and 20 are reasonable. This
is particularly important for the Shut down and Save option (Note the
warning above!)
4. The next line is for the name of the Sleep Thing, either 'asleep',
'schlafend', or 'dormant', depending on your Qpac2 language. This is
only meaningful if you should happen to use the Sleep Thing to put your
QD to sleep (buttonise it). Normally QD does its own thing when it
buttonises, so if you always use that - or don't know what Im talking
about - you should be alright!
5 & 6 QD comes, as far as I know, only in two language flavours, German and
English. However, there may be more.. Some tests inside PickQD need the
correct language to work. So on these two lines you need to enter the
No Name designation your QD uses, followed by the row column job name,
thus either:
QD NO NAME
QD row/column
or:
QD OHNE NAMEN
QD Zeile/Spalte
You can find these texts by starting up the version of QD that you
normally use with a blank document. Now list the Jobs in your system to
see what QD's job name is and what its row/column job is called in your
language and enter the names exactly as you see them, including the
leading 'QD '.
7. The next lines represent the command lines given to a new instance of QD
depending on the kind of file you are loading. You may need to check the
QD manual for details of the available options.
You can have as many lines as you like, but only one for each extension.
Each line starts with an extension name, eg txt, bas, link, .. followed
by a space, followed by the command line you wish to give QD for that
extension.
The first of these lines starts with an asterisk. This line is the
fallback command line that will be used for all instances for which no
extension has been defined.
Extensions can be up to 6 characters long, and the command line itself
can be up to 120 characters long. Anything beyond these values will be
truncated! So if you exceed them you will not get the results you
expected. (You can, of course, alter the code and re-compile if you
really need to!)
PickQD always prefixes the following to the command line, so you should
not add these again: \f <filename> \d <directory>
In use
======
You may need to "tune" PickQD to your particular platform(s). First try
buttonising and unbuttonising a bunch of files. See to it that all files
are processed. Reduce the "breather" time (see Configuration) until you see
files being missed out, then increase the time back up again. Shutting
down, especially with save may require longer breathers even though QD
operates autonomously once the command has been accepted, as the machine
will be busy with the file operation.
PickQD has, at present, five commands:
0 - New QD -
1 - Buttonise QDs -
2 - Unbutton QDs -
3 - ShutDown No Save -
4 - ShutDown & Save -
You invoke the command either by clicking on it or pressing its number
0 New QD
Fires up FSEL so you can select a file to load. Alternatively you
can manually enter a file name here of an existing or a new file.
If the file doesn't exist, this will be its name, otherwise it will
load the existing file.
If no instances of QD are running, FSEL is the first thing youll
see, not the standard menu.
1 Buttonise QDs
This causes all running instances of QD to be buttonised
2 Unbutton QDs
This wakes all buttonised instances of QD
3 ShutDown No Save
This shuts down all running instances of QD that don't contain
unsaved data.
4 ShutDown & Save
This shuts down all running instances of QD. If any are flagged as
changed (and only then) the file is first saved, overwriting any
previous version. Then the instance of QD is shut down. (QD can be
configured to backup a previous version of a file on saving. Check
out the QD manual!)
If two or more instances have the same file name NEITHER of them
are saved nor shut down! (You may inadvertently have altered and/or
saved, both/either file, so you have to decide manually what to do
with them.)
If instances of unsaved files havent been given a file name yet,
they will be also not be shut down.
See warning note at the top of this document!
The remaining items on the list are the file names of the running instances
of QD. Click any of those or type their leading number/letter to pick that
instance to the top - even if it is sleeping/buttonised.
Troubleshooting
===============
If you load a whole bunch of QDs at once, for example via Qpac2 and
FileInfo2, or by some other automated process, QD wont have time to set
the job name for each of those files! (that's a QD "issue", not a PickQD
one). So you get lots of jobs called QD - and nothing else. PickQD tries
to give these jobs a second chance to set a name, so they all get picked to
the top of the pile on the first occasion PickQD is invoked after such a
mass execution(!) event.
If you have a large number of QDs running at once and want to process them
all (buttonise, shut down, etc) some may get left behind. Consider changing
the breather (third line in PickQD_cfg). Either add on a few ticks, or
reduce by a few ticks (slower is not always better!) You may never hit a
perfect sweet spot, as there are so many external variables. But once youve
found a "comfortable" value, stick with it. And you can always re-run the
shut down or other process a couple of times.
Sometimes, of course, a recalcitrant QD wont go away. You may find, if
you have configured QD to have a solid Changed File indicator rather than
that annoying blinking one, that it is stuck in the off position although
the file has actually changed. Just do a CTRL + 'x' in the offending QD to
confirm whether it was a glitch or not.
Two instances of QD with the same file name cannot be shut down with the
save option - even if neither file has been changed. This is a safety
feature.
Program Notes
=============
This program started off as a quick hack but has evolved over the years.
It could do with a complete rewrite!
V0.07 was a partial rewrite, but some ancient code (and methods) remain.
V0.08 is a minor update: Since Id let the FSEL Thing name be user-
determined in some recent programs (for some reason) it wouldnt make sense
if other programs could only use the default name. Hence this update.
Software status
===============
V0.08, pjw, 2022 May 10
Toolkit source code available at Knoware.no
Conditions of use and DISCLAIMER as per Knoware.no
QL Software