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.


        er% = PICKJOB%([#chan,] jid [, wake%])

        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 and DISCLAIMER as per Knoware.no