| IBM PC Character Set | IBM PC Display Attributes | |
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 system, and the data items and procedures you need to write into your program.
The descriptions of the available routines are at the end of the chapter.
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:
The environment codes the run-time system returns are the best representation of the generic characters available in the current environment.
This is preferable to hard-coding an environment code, which makes your program specific to one environment.
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 run-time system intervenes and interprets the environment code when necessary.
This COBOL system provides the CBL_GET_SCR_LINE_DRAW call-by-name library routine for retrieving environment-specific codes from the run-time system at run time.
CBL_GET_SCR_LINE_DRAW is very flexible, enabling you to:
CBL_GET_SCR_LINE_DRAW retrieves environment codes from the run-time system.
You can request CBL_GET_SCR_LINE_DRAW to send you:
The routine requires two parameters:
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:
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.
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 line, and no South line.
A proprietary code is used to express this kind of description as a single byte:
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.
You can request a single-byte or double-byte version of the code. The following sections show you how to request codes.
To request a table of single-byte codes:
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 run-time system 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.
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.
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.
To request a table of double-byte codes:
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 run-time system 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.
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.
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. 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.
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.
chars2-function-code. line-draw-code. 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
To request a single double-byte code:
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.
chars2-function-code. line-draw-code. 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
When the current environment tries to represent each of the 256 possible generic line-drawing characters, there are three possibilities:
The run-time system 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.
If the current environment is not capable of displaying the character you have requested, the run-time system uses the following rules to determine what character should be displayed in its place:
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.
Some applications need to know if substitutions have taken place. To
make this possible, the run-time system 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:
| Bit |
Meaning |
|---|---|
| 2 | Extended lines are not supported and have been mapped. |
| 1 | Double lines are not supported and have been mapped. |
| 0 | Single lines are not supported and have been mapped. |
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:
| Decimal Value |
Meaning |
|---|---|
| 7 | Extended, single, and double lines are not supported, so were mapped to ASCII characters. |
| 6 | Extended and double lines are not supported, so were mapped to single lines. |
| 5 | Extended and single lines are not supported, so were mapped to double lines. |
| 4 | Extended lines are not supported, so were mapped to single lines. |
| 3 | Double and single lines are not supported, so were mapped to extended lines. |
| 2 | Double lines are not supported, so were mapped to single lines. |
| 1 | Single lines are not supported, so were mapped to double lines. |
| 0 | All line types are supported, so no mappings took place. |
There are two routines to help you find appropriate characters for your character user interfaces, independent of environment:
| CBL_GET_SCR_GRAPHICS | Get graphics characters |
| CBL_GET_SCR_LINE_DRAW | Get line drawing characters |
These routines are described in the following sections.
The COBOL system call-by-name library routines (those of the form CBL_name_name) use type definitions and COBOL CALL prototypes; this helps you to ensure that all calls to these routines are valid. For further information see the section Using the Library Routine TYPEDEFs and CALL Prototypes in the chapter Library Routines in your Programmer's Guide to Writing Programs.
To ensure that the type definitions and CALL protoypes are used by your program, you should include the copyfile $COBDIR/cpylib/cblproto.cpy in your program. cblproto.cpy must be copied before the Identification Division of the program being compiled.
Returns operating system independent codes for graphics characters.
call "CBL_GET_SCR_GRAPHICS" using graphics-params
returning status-code
graphics-params A
group item predefined as cblt-get-scr-graphics-buffer,
containing the following subordinate items: cblte-gsgb-flag cblt-x1-compx. cblte-gsgb-buf-size cblt-x2-compx. cblte-gsgb-buf. Group
item defined as: cblte-gsgb-up-arrow. Group
item defined as: cblte-gsgb-up-arrow-dbflag cblt-x1-compx. cblte-gsgb-up-arrow-arrow cblt-x1-compx. cblte-gsgb-down-arrow. Group
item defined as: cblte-gsgb-down-arrow-dbflag cblt-x1-compx. cblte-gsgb-down-arrow-arrow cblt-x1-compx. cblte-gsgb-right-arrow. Group
item defined as:
cblte-gsgb-right-arrow-dbflag cblt-x1-compx.
cblte-gsgb-right-arrow-arrow cblt-x1-compx. cblte-gsgb-left-arrow. Group
item defined as:
cblte-gsgb-left-arrow-dbflag cblt-x1-compx.
cblte-gsgb-left-arrow-arrow cblt-x1-compx. cblte-gsgb-maximize. Group
item defined as: cblte-gsgb-maximize-dbflag cblt-x1-compx.
cblte-gsgb-maximize-char cblt-x1-compx. cblte-gsgb-minimize. Group
item defined as:
cblte-gsgb-minimize-dbflag cblt-x1-compx.
cblte-gsgb-minimize-char cblt-x1-compx. cblte-gsgb-check. Group
item defined as: cblte-gsgb-check-dbflag cblt-x1-compx. cblte-gsgb-check-char cblt-x1-compx. cblte-gsgb-restore. Group
item defined as: cblte-gsgb-restore-dbflag cblt-x1-compx. cblte-gsgb-restore-char cblt-x1-compx. cblte-gsgb-radio. Group
item defined as: cblte-gsgb-radio-dbflag cblt-x1-compx. cblte-gsgb-radio-char cblt-x1-compx. cblte-gsgb-scroll. Group
item defined as: cblte-gsgb-scroll-dbflag cblt-x1-compx. cblte-gsgb-scroll-char
cblt-x1-compx. cblte-gsgb-rubber-band. Group
item defined as: cblte-gsgb-rubber-band-dbflag cblt-x1-compx. cblte-gsgb-rubber-band-char cblt-x1-compx. cblte-gsgb-sysmenu. Group
item defined as: cblte-gsgb-sysmenu-char-dbflag cblt-x1-compx. cblte-gsgb-sysmenu-char-char cblt-x1-compx. cblte-gsgb-editor-char. Group
item defined as: cblte-gsgb-editor-char-dbflag cblt-x1-compx. cblte-gsgb-editor-char-char cblt-x1-compx. cblte-gsgb-editor-char. Group
item defined as: cblte-gsgb-editor-char-dbflag cblt-x1-compx. cblte-gsgb-editor-char-char cblt-x1-compx. cblte-gsgb-hyhelp-tab. Group
item defined as: cblte-gsgb-hyhelp-tab-dbflag cblt-x1-compx. cblte-gsgb-ehyhelp-tab-char cblt-x1-compx. cblte-gsgb-hyhelp-btab. Group
item defined as: cblte-gsgb-hyhelp-btab-dbflag cblt-x1-compx. cblte-gsgb-ehyhelp-btab-char cblt-x1-compx. status-code See
Key in the Preface
|
Type of character code to return:
|
||||||
cblte-gsgb-buf-size |
Length of cblte-gsgb-buf in bytes. The
normal value of cblte-gsgb-buf-size is 30, although by
specifying a smaller value you can request only the graphics values you
require. You must not set |
cblte-gsgb-buf-size
|
Number of bytes filled. | ||||||||
cblte-gsgb-buf |
Character codes for each entry that is completely
contained in the cblte-gsgb-buf-size byte count.
The contents of any character code which is only partially in the byte
count is undefined. Any character codes wholly outside the byte count
are ignored. The byte count should include the whole of any DBCS character-part, even if DBCS is not requested or expected. For the |
||||||||
status-code |
Return status:
|
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.
call "CBL_GET_SCR_LINE_DRAW" using function-code
line-draw-table
returning status-code
function-code |
cblt-x1-compx. | ||||||||||||||||||||||||
Contains one of the following:
|
|||||||||||||||||||||||||
line-draw-table |
Group item defined as: With function-code = 0:
With function-code = 1:
With function-code = 2:
With function-code = 3:
|
||||||||||||||||||||||||
status-code |
See Key in the Preface |
With function-code = 2 or 3:
line-draw-code |
The offset (shape description) of the character required. |
line-draw-code |
Byte filled in by the run-time system to determine any
mapping that has taken place in the table as follows:
For bits 0 through 2, line types are mapped to the first available of single, double, extended or ASCII character. |
With function-code = 0:
line-draw-char
|
The single-byte line drawing table. Bytes in the table
are arranged as follows:
|
With function-code = 1:
DBCS-line-draw-char
|
The double-byte line drawing table. Bytes in the table are arranged as follows:
|
With function-code = 2:
line-draw-char |
The requested single single-byte line drawing code. |
With function-code = 3:
DBCS-line-draw-char
|
The requested single double-byte line drawing code. |
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:
| 00 | In the given direction, there is no line |
| 01 | There is a single-thickness line |
| 10 | There is a double-thickness line |
| 11 | There is an extended-type line. |
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:
| North: | 01 (single) |
| South: | 00 (blank) |
| West: | 00 (blank) |
| East: | 10 (double) |
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.
Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| IBM PC Character Set | IBM PC Display Attributes | |