IBM PC Character Set

IBM PC Display Attributes

Chapter 24: Generic Line Drawing

The generic line-drawing system enables you to write source programs that run unmodified in any supported environment and produce the best possible representation of graphic characters available in that environment.

This chapter tells you about the strategy you can use to achieve this, the services provided by the Run-time Environment (RTE), and the data items and procedures you need to write into your program.

The descriptions of the available routines is at the end of the chapter.

24.1 Overview

There are 256 possible generic line-drawing characters, each represented by a code in the range 0 through 255. These are called generic codes.

Generic codes are a logical description of line-drawing characters. See the section Finding the Character You Want for an explanation of how to find the code for any character.

The strategy you use to take advantage of generic line drawing works as follows:

1. As part of initialization, your program asks the RTE for the environment-specific codes of any characters that it needs. These are called environment codes.

   You can request:

   • The whole set of generic line-drawing characters.

   • Individual line-drawing characters, specified by their generic code.

   The environment codes the RTE returns are the best representation of the generic characters available in the current environment.

2. You can store these environment codes as either:
   • Named data items.

   • Subscripted entries in a table, where the subscript is the generic code.

3. Depending on the way you chose to store the environment codes, you hard-code a data item name or generic code into your program wherever graphic characters are needed.

   This is preferable to hard-coding an environment code, which makes your program specific to one environment.

4. The reference is used to find the environment code (determined during initialization) then sent to the environment (for instance as a parameter of CBL_SCR_WRITE_CHARS).

As a result, whatever code is sent to a supported environment at run time is automatically correct for that environment - even if the environment was unknown when the program was written.

In certain cases, for example, when the environment requires a shift to graphics mode before receiving the graphical character code, the RTE intervenes and interprets the environment code when necessary.

24.2 Operation

UNIX:
To use generic line drawing on UNIX, the COBCTRLCHAR environment variable must either not exist, or be set to N or n. If it is set to Y or y, generic line-drawing codes are not be interpreted as such , but are sent directly to the terminal.

This COBOL system provides the CBL_GET_SCR_LINE_DRAW call-by-name library routine for retrieving environment-specific codes from the RTE at run time.

CBL_GET_SCR_LINE_DRAW is very flexible, enabling you to:

• Access individual graphics characters or a complete table of 256 characters.

• Use single-byte or double-byte characters.

• Use descriptive names for individual characters or index a table of 256 characters using their generic codes (see the section Finding the Character You Want later in this chapter).

24.2.1 CBL_GET_SCR_LINE_DRAW

CBL_GET_SCR_LINE_DRAW retrieves environment codes from the RTE.

You can request CBL_GET_SCR_LINE_DRAW to send you:

• A complete set of 256 single-byte codes

• A complete set of 256 double-byte codes

• An individual single-byte code

• An individual double-byte code

The routine requires two parameters:

• A function code telling the RTE what information you want

• A data block

The function code is always of the same form, but the data (parameter) block is slightly different for different requests. If you are requesting a single character, you must state its generic code.

The call returns two sorts of information:

• The code(s) you requested.

• A code telling you about compromises the RTE had to make in the mapping. This could be, for example, that double lines were displayed as single lines because this is the best match that the environment can provide. See the section Replacing Unavailable Characters later in this chapter for a description of what the RTE does when it is unable to provide the character you requested.

Individual environment codes can conveniently be assigned to name variables, for example:

         03 horizontal-line pic x.

If you requested all of the 256 environment codes, they are returned as subscripted occurrences of a data item. The environment codes are ordered in the table so that the subscript is the character's generic code. See the section Finding the Character You Want for more information about this.

See the sections Requesting a Table of Character Codes and Requesting an Individual Character Code for information on how to make the calls.

24.2.2 Finding the Character You Want

This section explains how you can determine the generic code (subscript of data item line-draw-character) to use if you know the shape of the graphic character you want.

The following is a selection of line-drawing characters:

Each of them can be described as a cross made out of four strokes, called North, South, West, and East, out from the center. For example, the character:

can be described as a single North, West, and East lines, and no South line.

A proprietary code is used to express this kind of description as a single byte:

• Four pairs of bits are used to describe the North, South, West and East strokes of a cross, in that order.

• For each pair, 00 represents blank, 01 represents a single line, 10 represents a double line, and 11 indicates an extended line type, such as dotted.

Thus, the character above is coded as 01 00 01 01 = 69 decimal, or x"45".

This is a logical, convenient, and compact way of describing line-drawing characters. By translating them at run time into something that the current environment understands, applications can be made portable between different environments without changing the source.

24.2.3 Requesting a Table of Character Codes

You can request a single-byte or double-byte version of the code. The following sections show you how to request codes.

24.2.3.1 Requesting a Table of Single-byte Codes

1. You need the following data items declared in the Working-Storage Section of your program:

   01 chars2-function-code       pic x comp-x.
   01 chars2-parameter-block-0.
      03 line-draw-code          pic x comp-x.
      03                         pic x.
      03 line-draw-character     pic x occurs 255.

   The dummy item before line-draw-character is necessary because we want to refer to a table of items using a subscript in the range 0 through 255, but COBOL subscripts start from 1. By inserting a unnamed data item, with the same PICTURE clause as the recurring item, just before the recurring item, the dummy item is treated as the 0th occurrence of the recurring item.

   This technique requires you to specify the NOBOUND directive when compiling or generating your program. Failure to do so will result in RTS error 153 "Subscript out of range". Alternatively, you could create a table of 256 occurrences, and always add one to the generic code when referencing the table.

2. Request the table during initialization by moving 0 to chars2-function-code and making the call:

   call "CBL_GET_SCR_LINE_DRAW" using
                            chars2-function-code
                            chars2-parameter-block-0

   The returned value in line-draw-code tells you what compromises have been made due to the limitations of the current environment. See the section Checking for Substitutions for information on how to find out what substitutions have taken place.

3. When you need to use an environment code, you can access it using the generic code as a subscript.

   For example, to draw a tee with a double horizontal and single vertical line (generic code 00011010, decimal 26), assuming that a successful call to CBL_GET_SCR_LINE_DRAW has been made, the following code could be used:

   move line-draw-character(26) to character-buffer
   call "CBL_WRITE_SCR_CHARS" using screen-position
                                    character-buffer
                                    string-length.

24.2.3.2 Requesting a Table of Double-byte Codes

1. You need the following data items declared in the Working-Storage Section of your program:

     01 chars2-function-code          pic x comp-x.
       01 chars2-parameter-block-1.
          03 line-draw-code           pic x comp-x.
          03                          pic xx.
          03 dbcs-line-draw-character pic xx occurs 255.

   The dummy item before dbcs-line-draw-character is necessary because we want to refer to a table of items using a subscript in the range 0 through 255, but COBOL subscripts start from 1. By inserting a unnamed data item, with the same PICTURE clause as the recurring item, just before the recurring item, the dummy item is treated as the 0th occurrence of the recurring item.

   This technique requires you to specify the NOBOUND directive when compiling or generating your program. Failure to do so will result in RTS error 153 "Subscript out of range". Alternatively, you could create a table of 256 occurrences, and always add one to the generic code when referencing the table.

2. Request the table during initialization by moving 1 to chars2-function-code and making the call:

   call "CBL_GET_SCR_LINE_DRAW" using 
                             chars2-function-code
                             chars2-parameter-block-1

   The returned value in line-draw-code tells you what compromises have been made because of the limitations of the current environment. See the section Checking for Substitutions later in this chapter for more information on finding out what substitutions have taken place.

3. When you need to use an environment code, you can then access it using the generic code as a subscript.

   For example, to draw a tee with a double horizontal and single vertical line (generic code 00011010, decimal 26), assuming that a successful call to CBL_GET_SCR_LINE_DRAW has been made:

   move dbcs-line-draw-character(26) to character-buffer
   call "CBL_WRITE_SCR_CHARS" using screen-position
                                    character-buffer
                                    string length.

24.2.4 Requesting an Individual Character Code

You can request a single-byte or double-byte version of the code. If you need more than one character, you need to arrange to store characters returned, adding suitable items to the Working-Storage Section of your program. For example:

01 character-codes.
   03 top-left-corner       pic x.
   03 bottom-left-corner    pic x.
   03 top-right-corner      pic x.
   03 bottom-right-corner   pic x.
   03 horizontal-line       pic x.
   03 vertical-line         pic x.

The PICTURE clause of each level-03 item is x for single-byte codes, xx for double-byte codes.

You specify the particular character whose environment code you want by quoting its generic code. The following steps show you how to request a code.

24.2.4.1 Requesting a Single Single-byte Code

1. You need the following data items declared in the Working-Storage Section of your program:

   01 chars2-function-code          pic x comp-x.
   01 chars2-parameter-block-2.
      03 line-draw-code             pic x comp-x.
      03 line-draw-character        pic x.

2. Request an individual single-byte character by moving 2 to chars2-function-code.

3. Move the generic code for the character to line-draw-code.

4. Make the call:

   call "CBL_GET_SCR_LINE_DRAW" using
                             chars2-function-code
                             chars2-parameter-block-2

   The returned value in line-draw-code tells you what compromises have been made because of the limitations of the current environment. See the section Checking for Substitutions later in this chapter for more information on finding out what substitutions have taken place.

   You need to store the environment code returned in line-draw-character if you intend to use the call again before using the environment code you have just requested. For example:

   move line-draw-character to bottom-left-corner

5. When you need a character, you can then refer to it using the appropriate data item name.

24.2.4.2 Requesting a Single Double-byte Code

1. You need the following data items declared in the Working-Storage Section of your program:

   01 chars2-function-code            pic x comp-x.
   01 chars2-parameter-block-3.
      03 line-draw-code               pic x comp-x.
      03 dbcs-line-draw-character     pic xx.

2. Request an individual double-byte character by moving 3 to chars2-function-code.

3. Move the generic code for the character to line-draw-code.

4. Make the call:

   call "CBL_GET_SCR_LINE_DRAW" using
                             chars2-function-code
                             chars2-parameter-block-3

   The returned value in line-draw-code tells you what compromises have been made because of the limitations of the current environment. See the section Checking for Substitutions to find out what substitutions have taken place.

   You need to store the environment code returned in line-draw-character if you intend to use the call again before using the environment code you have just requested. For example:

   move line-draw-character to bottom-left-corner

5. When you need a character, you can then refer to it using the appropriate data item name.

24.2.5 Replacing Unavailable Characters

When the current environment tries to represent each of the 256 possible generic line-drawing characters, there are three possibilities:

• It can be represented exactly.

• It can only be represented by the substitution of another character.

• It cannot be represented by any character, and is shown by a space.

The RTE maps the generic codes onto the environment codes, including the best possible mappings for characters that do not have a direct equivalent in the environment. This means that your program does not have to perform any mapping.

This mapping is done automatically whenever you use CBL_GET_SCR_LINE_DRAW. The routine returns information about the mappings that have taken place, as described in the section Checking for Substitutions.

24.2.5.1 Choosing Substitutes to Use

If the current environment is not capable of displaying the character you have requested, the RTE uses the following rules to determine what character should be displayed in its place:

• If characters of a line type are not supported by an environment, they are replaced by corresponding characters of an available line type.

  For example, if your program requests the top left corner of a double-line box but the current environment is unable to display it, the character is replaced by the top left corner of a single-line box.

• The substitute is the first line type in this list that is available:
  1. Single

  2. Double

  3. Extended

  4. ASCII character

24.2.5.2 Checking for Substitutions

Some applications need to know if substitutions have taken place. To make this possible, the RTE returns a single byte, line-draw-code, that contains a value that tells you what mappings have occurred. The least significant three bits (0 through 2) have the following meanings when set to 1:

The five most significant bits (3 through 7) are currently reserved and your program does not need to check their settings.

Using the value of the bits 0 through 2, and the order of preference for substitution, the values of line-draw-code can be seen to have the following meanings:

24.3 Character Graphics Routines

There are two routines to help you find appropriate characters for your character user interfaces, independent of environment:

These routines are described here.

24.3.1 Description of Routines

CBL_GET_SCR_GRAPHICS

Returns operating system independent codes for graphics characters.

Syntax:

call "CBL_GET_SCR_GRAPHICS" using     graphics-params 
                            returning status-code

Parameters:

graphics-params             Group item defined as:
    graphics-flag               pic x comp-x.
    graphics-buf-size           pic x(2) comp-x.
    graphics-buf            Group item defined as:
        dbcs-up-arrow           Group item defined as:
            up-arrow-dbflg          pic x comp-x.
            up-arrow                pic x.
        dbcs-down-arrow         Group item defined as:
            down-arrow-dbflg        pic x comp-x.
            down-arrow              pic x.
        dbcs-right-arrow        Group item defined as:
            right-arrow-dbflg       pic x comp-x.
            right-arrow             pic x.
        dbcs-left-arrow         Group item defined as:
            left-arrow-dbflg        pic x comp-x.
            left-arrow              pic x.
        dbcs-maximize           Group item defined as:
            maximize-dbflg          pic x comp-x.
            maximize-char           pic x.
        dbcs-minimize           Group item defined as:
            minimize-dbflg          pic x comp-x.
            minimize-char           pic x.
        dbcs-check              Group item defined as:
            check-dbflg             pic x comp-x.
            check-char              pic x.
        dbcs-restore            Group item defined as:
            restore-dbflg           pic x comp-x.
            restore-char            pic x.
        dbcs-radio              Group item defined as:
            radio-dbflg             pic x comp-x.
            radio-char              pic x.
        dbcs-scroll             Group item defined as:
            scroll-dbflg            pic x comp-x.
            scroll-char             pic x.
        dbcs-rubber-band        Group item defined as:
            rubber-band-dbflg       pic x comp-x.
            rubber-band             pic x.
        dbcs-sysmenu            Group item defined as:
            sysmenu-dbflg           pic x comp-x.
            sysmenu-char            pic x.
        dbcs-editor-char        Group item defined as:
            editor-char-dbflg       pic x comp-x.
            editor-char             pic x.
        dbcs-hyhelp-tab         Group item defined as:
            hyhelp-tab-dbflg        pic x comp-x.
            hyhelp-tab              pic x.
        dbcs-hyhelp-btab        Group item defined as:
            hyhelp-btab-dbflg       pic x comp-x.
            hyhelp-btab             pic x.
status-code                 See Key in the Preface

On Entry:

On Exit:

Comments:

This routine is not available using the static linked run-time system (16-bit COBOL system) on DOS, Windows and OS/2.

CBL_GET_SCR_LINE_DRAW

Returns a table of values defining the character values required by the run-time system screen output routines to correctly display given line drawing characters.

Syntax:

call "CBL_GET_SCR_LINE_DRAW" using    function-code    
                                   line-draw-table 
                            returning status-code

Parameters:

With function-code = 0:

With function-code = 1:

With function-code = 2:

With function-code = 3:

On Entry:

With function-code = 2 or 3:

On Exit:

With function-code = 0:

With function-code = 1:

With function-code = 2:

With function-code = 3:

Comments:

When requesting a single line drawing character (function-code = 2 or 3), the line-draw-code parameter is used to tell the run-time system which character you require. The line-draw-code parameter for a given line-drawing shape can be calculated by splitting a byte into four bit-pairs. Each bit-pair defines the type of line that you want to appear in one of the four directions:

   Bit:   |  7   6  |  5   4  |  3   2  |  1   0  | 
          |  North  |  South  |   West  |   East  |

Each bit-pair can have one of the following values:

The extended line type is available only for systems which have additional types of line drawing, such as dotted lines. If a system has more than one additional type, only one can be used at a time.

For example, if you wished to find out the screen handler's character code for a line which would define the bottom-left of a box with single thickness sides and a double thickness bottom, you would make the following calculations:

Bit-pairs:

This gives the binary value of 01000010 or a decimal value of 66. Therefore, you would move 66 to line-draw-code before calling CBL_GET_SCR_LINE_DRAW in order to obtain the correct character for this shape.

If you use function-code = 0 or 1 to obtain the full line drawing table, a given character can be located in the table using the bit-pair algorithm described above, which yields a numeric value for a given shape. However, by default, COBOL subscripts begin at one, not zero. Therefore, if you use the following construct to obtain the full line drawing table:

     03 line-draw-char       pic x occurs 256 times.

you need to add 1 to the result of the bit-pair algorithm to locate the correct character (and, therefore, need a subscript which is larger than one byte).

However, you can use the following construct to obtain the table:

With function-code = 0:

     03 filler               pic x. 
     03 line-draw-char       pic x occurs 255 times.

With function-code = 1:

     03 filler               pic x(2). 
     03 DBCS-line-draw-char  pic x(2) occurs 255 times.

You must ensure that the NOBOUND Compiler directive is set to enable you to use subscripts 0 to 255, which map directly onto the result from the bit-pair algorithm.

IBM PC Character Set

IBM PC Display Attributes