#436 screenio adjustments: attributes + runtime-adjustable via CONTROL/COLOR

[Simon Sobisch]

Recently added were CONTROL (a literal or a variable that contains screen attributes as text names and COLOR (a variable that contains screenio attributes as calculated integer, an ACUCOBOL extension).

Everything you can use this for is also available with reserved words, which are checked at compile time, on runtime unsupported attributes are just skipped conflicting/duplicate attributes are handled from left to right.
The parsed attributes for CONTROL can be seen in https://sourceforge.net/p/gnucobol/code/5052/tree//branches/gnucobol-3.x/libcob/screenio.c#l655, the numbers for CONTROL around line 482+

Together with those changes the screen attributes LEFTLINE, RIGHTLINE(GC extension), OVERLINE are now supported - but those are commonly not available (so far I only know of PDCurses that support those). LEFTLINE and RIGHTLINE places a left/right line into every place of the field, therefore I guess they will be mostly used on a single character field.

As other extended screenio features "if the terminal / screenio library used does not support it, they are ignored"; which is possibly something that should be explicit noted - but that also is true for many others, for example BOLD, BLINK, BELL and even for colors (a monochrome display may map all these as black/white/gray).

There is one thing special for CONTROL (an RM/COBOL extension), that was requested before and cannot be done portable otherwise - drawing of line characters. CONTROL "GRAPHICS" replaces a specific set of characters to single/double line drawing characters. See [r5057] for the change (the list in screenio.c shows which characters are mapped to which line drawing symbol, but the example that is included in the testsuite in that commit may show that better). Every character that is not in the list is taken over "as-is".

@dilodilo: You're maybe also interested in testing this -if you could help writing the text for these attributes in the programmer's guide / recheck them, that would be quite helpful.

[Simon Sobisch]

@dilodilo: please have a look at the referenced entries above to see both what CONTROL does and how to use it (seen in the new testsuite entry: you can specify CONTROL 'literal attr' or CONTROL data-item - especially the later is useful as it allows to change the screen attribute at runtime, for example to change the colors, make it bold, ...) - the supported attributes are also seen in this commit (the table, as noted in the text above).
CONTROL literal is most useful for CONTROL 'GRPAHICS).

If you have not executed the tests from make checkmanual then this may be a good time (if you build GnuCOBOL from source, otherwise you could copy/paste the interesting entries from the testsuite and execute them manually.

[Eugenio Di Lorenzo]

I've looked at the links above but frankly it's not enough for me.
If it's a feature that other compilers also have, then can you suggest I look at the manual for those compilers somewhere on the web?

[Simon Sobisch]

The issue here is that the PG is a free document under a free license - and therefore one should not "copy" the content of another non-free documentation. The best thing to reach that is to document what is implemented "directly".

But we could have a look at the links together, that may be useful.
This still does not hinder anyone to search for "RM COBOL DISPLAY CONTROL phrase" (I think that's where it originally came from and CONTROL "GRAPHICS" is so far likely an RM/COBOL only extension) or "ACU COBOL DISPLAY COLOR phrase", but for the documentation part I highly suggest to document from the implementation and the examples (make checkmanual in a source build, or copy/paste from tests/testsuite.src/run_manual_screen.at) instead.
If you don't build GC yourself you could checkout the nightly binaries, the most current one for MinGW are available (30 day from now) at https://ci.appveyor.com/project/GitMensch/gnucobol-3-x-win32-posix/build/job/2q9qjfi1poi24863/artifacts

[Simon Sobisch]

ping @dilodilo - can we move this from Vince to you, or should it stay there?

[Eugenio Di Lorenzo]

Ok
I will write the documentation for the new CONTROL clause of the DISPLAY statement.
As always, Vince will be responsible for updating the PG.

[Vincent (Bryan) Coen]

On 13/01/2024 16:30, Eugenio Di Lorenzo wrote:

Ok
I will write the documentation for the new CONTROL clause of the
DISPLAY statement.
As always, Vince will be responsible for updating the PG.

Include for what version of the compile they apply to, also what
compiler switches have to be set again that apply these, i.e., specific
Compiler such as RM, ARC, IBM, MF Visual, what ever.

For every one else that has made changes to the compiler please specify
in detail exactly what changes have taken place and where possible the
text to include and where - it will make my life easier without me
trying to guess your intentions or worse "ASSUME".

At 76 year old - I have stopped "Assuming", actually have  stopped, many
years ago when writing manuals or programs.

[Eugenio Di Lorenzo]

Hi Vince,
what you rightly ask, in this case, can only be detailed and specified by Simon.

[Eugenio Di Lorenzo]

Hi,
below is a draft documentation of the new CONTROL and COLOR clause to be added to statement 7.8.12.4. DISPLAY data-item.

I have reported both the complete syntax scheme with all the current features to which I have added the CONTROL and the COLOR clause.
I suggest copying it in its entirety, not just the lines with the CONTROL and COLOR clause, as I fixed some imperfections on the brackets.

The textual part should be validated by Simon.

It is not clear to me whether the CONTROL and COLOR clause have also been implemented for ACCEPT.
In this case, chapter 7.8.1.4 would also need to be updated. ACCEPT data-item.
Please Simon, let me know.

PS. If the format of this post isn't right, I'll attach a TXT file with the same content.

DISPLAY identifier-1 [ UPON CRT|CRT-UNDER ]
~~~~~~~                ~~~~ ~~~ ~~~~~~~~~
         OMITTED
         ~~~~~~~
        [ AT { | LINE NUMBER { integer-1    }                    | } ]
          ~~ { | ~~~~        { identifier-2 }                    | }
             { | COLUMN|COL|POSITION|POS NUMBER { integer-2    } | }
             { | ~~~~~~ ~~~ ~~~~~~~~ ~~~        { identifier-3 } | }
             {                                                     }
             { { integer-3    }                                    }
             { { identifier-4 }                                    }
        [ WITH [ Attribute-Specification ]...
          ~~~~ 
               [ SCROLL { UP   } [ { integer-4    } LINE|LINES ] ]
                 ~~~~~~ { ~~   }   { identifier-5 }
                        { DOWN }
                        { ~~~~ }
              [ SIZE     { integer-5       } ]
                ~~~~     { identifier-6    } 
              [ CONTROL  { literal-7    } ]
                ~~~~~~~  { identifier-7 }   
              [ { COLOR  } IS  { integer-8    } ]
                { COLOUR }     { identifier-8 }
                  ~~~~~~                  
              [ NO ADVANCING ]
                ~~~~~~~~~~~~
        [ ON EXCEPTION imperative-statement-1 ]
             ~~~~~~~~~
        [ NOT ON EXCEPTION imperative-statement-2 ]
          ~~~     ~~~~~~~~~
[ END-DISPLAY ]
  ~~~~~~~~~~~

CONTROL phrase.

The CONTROL phrase allow dynamic (runtime as opposed to compile time) specification of characteristics.
Literal-7 must be a nonnumeric literal. Identifier-7 must be a nonnumeric data item.

The value of identifier-7 or literal-7 in the CONTROL phrase must be a character-string
consisting of a series of keywords delimited by commas; some keywords allow assignment
of a value by following the keyword with an equal sign and the value.
Blanks are ignored in the character-string.
Lowercase letters are treated as uppercase letters within keywords.
Keywords specified override corresponding static options specified as phrases.
Keywords may be specified in any order.
Keywords, which specify options that do not apply to the statement, are ignored.

The keywords that affect a DISPLAY statement are
BEEP, BLINK, CONVERT, REVERSE, UNDERLINE, ERASE, ERASE EOL, ERASE EOS, HIGH, LOW,
NO BEEP, NO BLINK, NO CONVERT, NO REVERSE, NO UNDERLINE NO ERASE.
The meanings of these keywords when they appear in the value of the CONTROL phrase operand are the same
as the corresponding phrases which may be written as static options of the DISPLAY statement,
with the addition of the negative forms to allow suppression of statically declared options.

GnuCOBOL provides three additional keywords in the CONTROL phrase that affect a DISPLAY field.
1. FCOLOR = color-name
When FCOLOR is present, color-name specifies the foreground color of the DISPLAY field.
This name is then used as the default value for subsequent DISPLAY statements in the program.
The initial default for color-name is white.
2. BCOLOR = color-name
When BCOLOR is present, color-name specifies the background color of the DISPLAY field.
This value is then used as the default value for subsequent DISPLAY statements in the program.
The initial default for color-name is black.
Following table contains a list of all the possible names for color-name.
The left column contains the valid color name.
The right column shows the color that appears when high intensity is specified (the default intensity).

    +--------------------------------------------------------------+
    |                 Valid COBOL Color Names                      |
    +-------------------+------------------------------------------+
    |Valid Color Names  |  High-Intensity Color Values (Defaults)  |
    +-------------------+------------------------------------------+
    |Black              |  Gray                                    |
    |Blue               |  Light Blue                              |
    |Green              |  Light Green                             |
    |Cyan               |  Light Cyan                              |
    |Red                |  Light Red                               |
    |Magenta            |  Light Magenta                           |
    |Brown              |  Yellow                                  |
    |White              |  High-Intensity White                    |
    +-------------------+------------------------------------------+

1. GRAPHICS
   The GRAPHICS keyword causes the characters in following table to be translated to line draw characters.
   Characters that are not listed in the following table are output unchanged.

    +-------------------------------------------------------------------+
    |                       Line Draw Characters                        |
    +-------------------+-----------------------+-----------------------+
    |Description        | Single-Line Character | Double-Line Character |
    |lower-right corner |        j(+)           |        J(+)           |
    |upper-right corner |        k(+)           |        K(+)           |
    |upper-left corner  |        l(+)           |        L(+)           |
    |lower-left corner  |        m(+)           |        M(+)           |
    |plus               |        n(+)           |        N(+)           |
    |horizontal line    |        q(-)           |        Q(-)           |
    |left tee           |        t(+)           |        T(¦)           |
    |right tee          |        u(¦)           |        U(¦)           |
    |bottom tee         |        v(-)           |        V(-)           |
    |top tee            |        w(-)           |        W(-)           |
    |vertical line      |        x(¦)           |        X(¦)           |
    +-------------------+-----------------------+-----------------------+

If the requested line draw characters are not available, the runtime system uses the best available characters.
If double-line characters are requested and only single-line characters are available, they are used.
If no line draw characters are available, then plus-characters, vertical bars, and dashes are used.

Sample program that demonstrates how boxes are drawn:

        >>SOURCE FREE
        IDENTIFICATION   DIVISION.
        PROGRAM-ID.      CONTROL1.
        DATA             DIVISION.
        WORKING-STORAGE  SECTION.
        01  success-flag PIC X VALUE 'Y'.
            88  success  VALUE 'Y', 'y'.
        77  LIN-START    PIC 99    COMP-5.
        77  LIN          PIC 99    COMP-5.   
        01  scr1 PIC X(75)
                VALUE 'Enter "y" if you see line draw characters. '
                & 'The first set (single/double)'.
        01  scr2 PIC X(75)
                VALUE 'uses HIGHLIGHT, the second uses '
                & 'LOWLIGHT, BLINK and MAGENTA.'.
        01  graphcontrol PIC X(50) VALUE 'HIGH, GRAPHICS'.
        PROCEDURE DIVISION.
            MOVE 2 TO LIN
            DISPLAY scr1 AT LINE LIN COL 2
            ADD  1 TO LIN
            DISPLAY scr2 AT LINE LIN COL 2
            MOVE 5 TO LIN-START
            PERFORM dspcol
            MOVE 12 TO LIN-START
            MOVE "LOW BLINK FCOLOR=MAGENTA GRAPHICS" TO graphcontrol
            PERFORM dspcol
            ACCEPT success-flag AT 1801 UPDATE REQUIRED 
            IF success AND COB-CRT-STATUS = 0
                GOBACK RETURNING 0
            ELSE
                GOBACK RETURNING 1.
        dspcol.
       *>   Single-line graphics
            MOVE LIN-START TO LIN
            DISPLAY "lqqqqwqqqqk" LINE LIN COL 05, CONTROL graphcontrol.
            ADD  1 TO LIN
            DISPLAY "x    x    x" LINE LIN COL 05, CONTROL graphcontrol.
            ADD  1 TO LIN
            DISPLAY "tqqqqnqqqqu" LINE LIN COL 05, CONTROL graphcontrol.
            ADD  1 TO LIN
            DISPLAY "x    x    x" LINE LIN COL 05, CONTROL graphcontrol.
            ADD  1 TO LIN
            DISPLAY "mqqqqvqqqqj" LINE LIN COL 05, CONTROL graphcontrol.
       *>   Double-line graphics
            MOVE LIN-START TO LIN
            DISPLAY "LQQQQWQQQQK" LINE LIN COL 20, CONTROL graphcontrol.
            ADD  1 TO LIN
            DISPLAY "X    X    X" LINE LIN COL 20, CONTROL graphcontrol.
            ADD  1 TO LIN
            DISPLAY "TQQQQNQQQQU" LINE LIN COL 20, CONTROL graphcontrol.
            ADD  1 TO LIN
            DISPLAY "X    X    X" LINE LIN COL 20, CONTROL graphcontrol.
            ADD  1 TO LIN
            DISPLAY "MQQQQVQQQQJ" LINE LIN COL 20, CONTROL graphcontrol.

Added a screenshot from sample program using "GRAPHICS"

COLOR Phrase

The COLOR phrase provides an alternate method for setting video attributes.
Integer-8 must be a numeric literal. Identifier-8 must be a numeric data item.
They can be set to different numeric values to express various combinations of colors and video attributes.
You may make combinations by adding the appropriate values together.
The following color values are accepted:

    +--------+--------------+-------------+
    |Color   |  Foreground  | Background  |
    +--------+--------------+-------------+
    |Black   |      1       |     32      |
    |Blue    |      2       |     64      |
    |Green   |      3       |     96      |
    |Cyan    |      4       |    128      |
    |Red     |      5       |    160      |
    |Magenta |      6       |    192      |
    |Brown   |      7       |    224      |
    |White   |      8       |    256      |
    +--------+--------------+-------------+

You may specify other video attributes by adding the following values:

    +-------------------------+--------+
    |Reverse video            |   1024 |
    |Low intensity            |   2048 |
    |High intensity           |   4096 |
    |Underline                |   8192 |
    |Blink                    |  16384 |
    |Protected                |  32768 |
    |Background low-intensity |  65536 |
    |Background high-intensity| 131072 |
    +-------------------------+--------+

You may also specify high intensity by adding "8" to the foreground color value.

Sample program that demonstrates how COLOR is used:

        >>SOURCE FREE
IDENTIFICATION DIVISION.
PROGRAM-ID. COLOR1.
*> Sample for using "COLOR" clause
DATA DIVISION.
WORKING-STORAGE SECTION.
01 wLIN            PIC     99 value zero.
01 wCOLOR          PIC 999999 value zero.

01 wBlack-Fore     PIC 999 value   1.
01 wBlack-Back     PIC 999 value  32.
01 wBlue-Fore      PIC 999 value   2.
01 wBlue-Back      PIC 999 value     64.
01 wGreen-Fore     PIC 999 value   3.
01 wGreen-Back     PIC 999 value  96.
01 wCyan-Fore      PIC 999 value   4.
01 wCyan-Back      PIC 999 value 128.
01 wRed-Fore       PIC 999 value   5.
01 wRed-Back       PIC 999 value 160.
01 wMagenta-Fore   PIC 999 value   6.
01 wMagenta-Back   PIC 999 value 192.
01 wBrown-Fore     PIC 999 value   7.
01 wBrown-Back     PIC 999 value 224.
01 wWhite-Fore     PIC 999 value   8.
01 wWhite-Back     PIC 999 value 256.

01 wReverseVideo              PIC 999999 value   1024.
01 wLowIntensity              PIC 999999 value   2048.
01 wHighIntensity             PIC 999999 value      4096.
01 wUnderline                 PIC 999999 value   8192.
01 wBlink                     PIC 999999 value  16384.
01 wProtected                 PIC 999999 value  32768.
01 wBackground-low-intensity  PIC 999999 value  65536.
01 wBackground-high-intensity PIC 999999 value 131072.

 PROCEDURE DIVISION.

  ADD 1 to WLIN
  compute wCOLOR = wCyan-Fore + wWhite-Back + wUnderline
  DISPLAY FUNCTION CONCATENATE ("XXX COLOR=" wCOLOR " XXXXXXXXX ") AT LINE wLIN COL 001 COLOR wCOLOR.  

  ADD 1 to WLIN
  compute wCOLOR = wBrown-Fore + wRed-Back + wHighIntensity  
  DISPLAY FUNCTION CONCATENATE ("XXX COLOR=" wCOLOR " XXXXXXXXX ") AT LINE wLIN COL 001 COLOR wCOLOR.

  ADD 1 to WLIN
  compute wCOLOR = wBrown-Fore + wRed-Back + wHighIntensity + wReverseVideo
  DISPLAY FUNCTION CONCATENATE ("XXX COLOR=" wCOLOR " XXXXXXXXX ") AT LINE wLIN COL 001 COLOR wCOLOR.

  ADD 1 to WLIN
  compute wCOLOR = wWhite-Fore + wGreen-Back + wBlink
  DISPLAY FUNCTION CONCATENATE ("XXX COLOR="  wCOLOR " XXXXXXXXX ") AT LINE wLIN COL 001 COLOR wCOLOR.

  STOP RUN.

[Simon Sobisch]

Both COLOR and CONTROL are valid for both ACCEPT and SCREEN (of course, they have to be available as reserved words).
COLOR takes both a (numeric) literal or a numeric integer.

Otherwise that explanation looks good to me.

[Eugenio Di Lorenzo]

sorry but your last post is not clear.

From yout previous post:
Both COLOR and CONTROL are valid for both ACCEPT and SCREEN (of course, they have to be available as reserved words).

maybe you wanted to write:
Both COLOR and CONTROL are valid for both ACCEPT and DISPLAY (of course, they have to be available as reserved words).

CONTROL and COLOR cannot be used in the SCREEN SECTION !
can you confirm ?

[Simon Sobisch]

They are implemented in ACCEPT and DISPLAY but not in the SCREEN SECTION (where they are parsed but raise a not-implemented warning).... thinking about that again, this would be relative easy to add without breaking compatibility (which was the reason that it was not implemented in the first place) using some hack (extending the existing cob_screen structure, but only handle the additional fields if the cob_module is 3.3 or newer).
Someone wants to provide a patch for that?

[Eugenio Di Lorenzo]

Hi Simon,
the previous post has been updated, now also contains documentation of the COLOR clause in addition to the CONTROL clause.
I had to do several tests using GC 3.2 from Arnold, to understand what it was.
Now I think your validation is necessary to verify that it is correct.
Vince will then be able to update the Programmers Guide.

[Eugenio Di Lorenzo]

Hi,
attached is the final documentation of the new CONTROL and COLOR clause to be added to statements 7.8.1.4. ACCEPT data-item and 7.8.12.4. DISPLAY data-item.

The documentation has been validated by Simon therefore Vincent can insert it into the PG.

[Vincent (Bryan) Coen]

The box of symbols for :

|left tee           | t(+)           |        T(Š)           |
    |right tee          |        u(Š)           | U(Š)           |
    |vertical line      |        x(Š)           | X(Š)           |

The special character after T, U and X are not understood by tex system
and are ignored - they are omitted from text.

Just what character is it ?

On 15/01/2024 15:46, Eugenio Di Lorenzo wrote:

Hi,
attached is the final documentation of the new CONTROL and COLOR
clause to be added to statements 7.8.1.4. ACCEPT data-item and
7.8.12.4. DISPLAY data-item.

The documentation has been validated by Simon therefore Vincent can
insert it into the PG.

Attachments:

• ACCEPT-DISPLAY-CONTROL-AND-COLOR.txt
  https://sourceforge.net/p/gnucobol/feature-requests/_discuss/thread/b7b077b0c4/c8e0/attachment/ACCEPT-DISPLAY-CONTROL-AND-COLOR.txt
  (18.8 kB; text/plain)

[Eugenio Di Lorenzo]

Attached screenshot shows original graphics characters.

[Eugenio Di Lorenzo]

Would it be possible to insert the correct graphic characters into the PG?

[Simon Sobisch]

Sure but - as noted also in the quoted docs: "system specific"; but if you find the texinfo module/font to add those, we can do so.

[Vincent (Bryan) Coen]

The tex package runs under Linux and as far as I know there is NO
provision for IBM chars.

There is even no point to me installing them on my system and I have no
idea if it will cuase issue with the rest of my production system if I do.

Normally IBM char sets are not used under *nix.

On 15/01/2024 21:02, Eugenio Di Lorenzo wrote:

Would it be possible to insert the correct graphic characters into the PG?

[Vincent (Bryan) Coen]

Could be possibly interesting to see what the rest of the text says
regarding Linux - which seems to imply (may be) that there is issues.

On 15/01/2024 19:36, Eugenio Di Lorenzo wrote:

Attached screenshot shows original graphics characters.

Attachments:

• CHARS.png
  https://sourceforge.net/p/gnucobol/feature-requests/_discuss/thread/b7b077b0c4/c8e0/541f/0175/attachment/CHARS.png
  (77.2 kB; image/png)
  

[Vincent (Bryan) Coen]

Can some one tell me how I can access these "Featurte Requests" as the do NOT appear under Tickets button.

[Simon Sobisch]

Am 15.01.2024 um 22:38 schrieb Vincent (Bryan) Coen:

Can some one tell me how I can access these "Featurte Requests" as the do NOT appear under Tickets button.

they are named "wish list" there - for historical reaons

[Eugenio Di Lorenzo]

I would say that for the moment we can eliminate these graphic symbols from the PG.
The description of each graphic symbol that is present in the table is sufficient.
Later, when we are able, we will insert the graphic symbols for even better documentation.

[Vincent (Bryan) Coen]

On 15/01/2024 22:30, Eugenio Di Lorenzo wrote:

I would say that for the moment we can eliminate these graphic symbols
from the PG.
The description of each graphic symbol that is present in the table is
sufficient.
Later, when we are able, we will insert the graphic symbols for even
better documentation.

I will for the moment leave it in as it serves as a reminder to insert
the correct font and NO have no idea how.

[Vincent (Bryan) Coen]

Done - see bug report for same thing el al.