PickJob%
========
Pick a given job to the top of the pile
This is a simple wrapper for iop.pick. Given a valid job ID it pick that
job to the top of the window pile. Its a bit like a random access CTRL c.
Optionally, you can send the picked job a Wake signal, which may have an
effect on PE jobs that listen for this signal. Eg if Wake is sent to Qpac2
Files it will re-read the directory and refresh the list of files.
Requirements and Limitations
----------------------------
PICKJOB% only requires that the Pointer Interface is present, although it
does not do a friendly test for this. PI is always the present in SMSQ/E,
but with Qdos and Minerva you need to load ptr_gen - preferably in your
boot file. The Window Manager is not required for PICKJOB%.
A number of toolkits implement the iop.pick call. The command may be
called WAKE or PTOP or PICK. With some you can specify a file name or
split job IDs, however PICKJOB% will only respond to the full job ID. Some
implementation allow passing a string with the wake signal, which gets
stuffed in the job's input buffer. Not so PICKJOB%.
PICKJOB% returns the error code as an integer. That means it cannot be
used to pass special error codes; only the standard Qdos ones.
Usage
-----
er% = PICKJOB%([#chan,] jid [, wake%])
where
er% is a simple error code, normally 0, or -2 (invalid job)
chan is an optional S*BASIC channel number (default is #0)
If parameter is present, it MUST be preceded by #
jid is the target job's ID (see below)
wake% is a flag: 0 => dont wake, 1 => send wake signal
The job ID must be given as a single long integer, eg
2031647, or $008B002A
or with recent versions of SMSQ/E or TK2
JOBID ie myself
JOBID(44, 152) ie job 44, tag 152
or JOBID('Files win1_prog_')
It is also possible to give PICKJOB% the argument -1, in which case it
will pick the bottom job to the top.
Software status
---------------
PICKJOB% is one of a suit of basic PI commands for use in compiled S*BASIC
programs that could be used in cases where only a tiny subset of commands
are required, and where including a full toolkit like qptr_bin or ptrmen_cde
would be an overkill.
V0.01, pjw, 2019 Jun 04
Conditions of use and DISCLAIMER as per Knoware.no
QL Software
