A developer recently sent in a question about how to query the current terminal foreground and background colors from an application, rather than by using the SET TERM command, which displays a number of the settings on the screen, e.g. ...

The question is interesting at multiple levels, not just for the basic "how to do it" (which like so many other programming details has multiple answers), but also for the implied "how to find it in the documentation". And it's a good excuse to review all of it together, which often leads to either improvements in the documentation, the understanding, or the code itself. So with advance apologies for not just answering the question, here we go...

Starting with the how to do it, let's look at how SET.LIT does it. Since the A-Shell LIT commands are actually all written in ASB (A-Shell BASIC), unlike the AMOS versions which were written in assembler, anything a LIT command can do, your application can do the same way. We don't automatically distribute the source to the LITs (mainly to keep them standardized), but we're happy to release in on request. In any case, the way SET.LIT does it starts with this include at the top of the program:

The common include files in the ashinc: ersatz directory (normally [907,16]) are available from the SOSLIB repository. Unlike most BSI modules (which contain only functions, or at least jump over any code so that including them at the top of a program doesn't cause them to inadvertently execute, this one is designed for fall-through execution, and thus must be at the top of the program)...

So in other words it just does an XCALL TRMCHR, which is the real secret to querying the TeRMinal CHaRacteristics. (If you knew that, you'd know how to find it in the doc, but unfortunately it's not obvious.)

XCALL TRMCHR takes two arguments -- a status variable and a structure containing the various characteristics / settings, both of which are mapped in the trmchr.map file. (Note that although the ++include statement doesn't specify the location of trmchr.map, it defaults to the location of the current source file (ashinc:trmchr.bsi). The map file contains:

That's probably more than enough information, but just to complete the circle, here's the actual code with SET.LIT that displays the result of the terminal width, height and colors...

(The other details output by SET TERM come from the MX_BEVEL and MX_SYSBCLR xcalls.)

So that's one way to do it. But as you're probably thinking, it seems like a lot of stuff just to query a couple of terminal settings. To make these kinds of repetitive low-level tasks simpler to code, we've created many utility functions which encapsulate the messy details, making it easier to just get what you want with minimal coding. You can find the entire set in the SOSFUNC repository (aka 907,010 within the SOSLIB repository). Tip: to help you find what you're looking for within that set of library functions, use the FUNCIDX command.

The SOSFUNC:FNTRMCHR.BSI module contains the following handy functions:

As it turns out, when I first looked this morning, the last two functions didn't exist, which was rather inconvenient for this discussion, but fortunately were very easy to add. (Which is another good reason to post questions like this on the Forum, as it often leads to gaps being filled in.)

So to complete this alternate how to do it, all you need is to include the sosfunc:fntrmchr.bsi and then call the functions that return the details you want, e.g.

As for the "how to find it in the documentation", I'm afraid I don't have a good answer. Normally I would suggest using either the index or the keyword search to search, but although there are several hits for both "terminal" and "color", I'm not sure any of them lead to XCALL TRMCHR or the Fn'TRMCHR'xxx() functions. On the bright side, asking the question helps us improve the documentation. (Memo to Ty: let's add a couple of search and index terms that mention "querying terminal characteristics" and lead to TRMCHR.)