PRTSTR%
                                 =======

       PRTSTR% is a function to print a string to screen - with timeout.

On Qdos systems, or SMSQ/E systems with background screen updating
switched off (PE_BGOFF), if a window is buried - even partially, any
action that attempts to access that window is put on hold until the window
is again free.

So if you have a program that is processing some data in the background,
but also tries to keep the user updated by printing its progress on screen,
that processing is halted should the window become buried. This is not
always desirable!

With background updating switched on (impossible in Qdos without a special
screen driver) background processing can continue and the progress display
is maintained correctly throughout.

PRTSTR% is a poor man's substitution, as it would not maintain such progress
truthfully; if it finds a window unavailable it simply skips the update and
continues processing.

But it is not only printing that is affected by a locked window, setting
the ink or paper colour, as well as positioning commands like AT or CURSOR
will also halt your program. So PRTSTR% packages many of the most likely
functions.


New:
====

This version also allows you to print to the channel of another running
job - provided you know its Qdos channel ID. You can use

        ID = CHID(#chan_no%)

on the other job for this. You still have to precede the channel ID with a
hash, eg

        er% = PRTSTR%(#$10001; 'Hello world!' & CHR$(10))

would print 'Hello world!' to job #0's channel #1. Note that the only
/external/ channel you cannot print to is job #0's channel #0!

Note also that due to job scheduling this may not always work as you might
intend, so experiment!

To get the channel ID of an extraneous job, including ones you dont have the
source code to, you can use CHIDX. Both CHID and CHIDX can be found under
Toolkits at Knoware.no.

Check out the demo in io_prt_demo_Demo_txt! (SMSQ/E only, although it is
modifiable.)


Usage:
======

[ ] => optional
{ } => repeated group, also * => repeat etc
 |  => or

Note the use of separators! They are all significant!

Syntax:

 er% = PRTSTR%(
       [#ch% | #channelID]           Channel number (default #1) or ID
       [, timeout%]                  Timeout: -1 = forever, 0 = none (def)
       {                             Repeat this bit:
        [! atx%, aty%] |              AT char position x/y - always two!
        [! atx%! aty%]                AT pix position x/y - always two!
        [TO tabx%]                    TO TAB x-position
        [\ ink [, strip]]             INK and STRIP colour (mode 0..33)
        [; string[$] | char% [, ]* ]  list of strings or (int%) char bytes
       }                             End repeated parameters
      )                              End function

er% contains any IO error code, usually 0 or -1, ie OK or Not Complete.

Paper colour should be set in advance, as PRTSTR% only supports the strip
colour. Also the colour mode, COLOUR_QL, COLOUR_NATIVE, or COLOUR_24
should be set in advance; PRTSTR% supports them all.

To give you a basic idea of how it works, play with the demo_PRTSTR_bas
program (LRUN it in an SBASIC). As it runs, cover the window with another
program window. High beep implies no error, low beep usually means not
complete. So unless timeout is set to -1 (wait until complete) the program
will keep functioning even when its window is locked.

As it stands, the demo is set to 10/50 second, so when the window is
burried you should hear a grunting beep. SMSQ/E users should set PE_BGOFF
to test, and PE_BGON when done.


Program Status
==============

V0.03, pjw, 2004 Feb 01
V0.03, pjw, 2021 Dec 28, added key and link files for stand-alone version
V0.04; pjw, 2025 Oct 04, added back print to external job's channel.
                         Updated documentation. Updated and added demos.

               Conditions of use and DISCLAIMER as per Knoware.no

Generated by QuickHTM, 2025 Oct 04