IBM PC Display Attributes |
This chapter describes the way in which you can control the appearance (attributes) of characters on the screen. This system enables you to do so in a way that is portable between different environments and hardware.
Descriptions of the routines available are provided at the end of this chapter.
Your personal computer can display text on the screen in many ways. On a monochrome (two-color) display the text can be displayed in combinations of different intensities, underlined, reverse video, and blinking. On a color display, the text can also be displayed in different colors on a colored background.
The generic attributes system gives you the following advantages:
Each character position on the screen has an associated byte (or bytes for double-byte character set) defining the character to be displayed. In addition, each character position also has an associated byte of attribute information. This attribute byte controls the character's appearance.
This byte tells the system how the character appears, specifying:
Generic attributes were introduced into Micro Focus COBOL in V3.0. Before that, all code for handling display attributes using an attribute byte, such as the screen handling library routines or Panels, was specific to the environment the program was being run on. The program could not be moved to another environment without having different attributes coded.
Programs that display attributes without using an attribute byte, by using Enhanced ACCEPT/DISPLAY statements or Screen Section (both using Adis), are already portable.
The increased need to make programs portable across environments without code changes, particularly between IBM-PC and UNIX machines, has made it necessary to introduce generic attributes.
The generic attributes system does not give you a default set of attribute values that you can hard-code into your programs in order for them to work consistently across all environments. Instead, it is a method of requesting attributes in a generic manner at run time, and assigning those attributes to specified positions in a table of 256 attributes. This is the attribute table, and is held by the run-time system (RTS).
So, by organizing the attribute table correctly you can display colors on any environment.
Each character position on the screen has one byte of attribute information associated with it, giving up to 256 attributes. This means that you can display up to 256 different attributes on your screen at one time, depending on the limitations imposed by your hardware.
For each entry, the attribute table stores:
The bits of the character attribute byte are like switches that turn their corresponding effect on and off. The RTS translates this information into terms that the current environment can understand.
The effect of each bit is environment-independent. The section Character Attribute Codes later in this chapter lists these effects.
The foreground and background color entries are pointers indexing a further table that is part of the environment. This table is called the colormap, and each entry in it represents a color.
Each color is described in amounts of the primary colors red, green and blue (RGB) that the hardware needs to provide the color. Depending on the environment, you can mix your own colors in some or all of the colormap entries.
The color corresponding to a particular colormap entry depends on the environment, its defaults, and what colors you have mixed yourself. Call-by-name routines exist to help you find out what is in your current environment at run time. See the section Finding Out About the Current Environment for further information.
Your program can manipulate the attribute table and colormap by using the RTS call-by-name routines discussed in this chapter.
When a program calls the RTS with a request to write an attribute to the screen, the call passes an attribute byte. The RTS uses this byte to look up the corresponding entry in its attribute table. It then uses the color values to index the colormap and translates the character attribute byte into a form acceptable to the current environment.
If you use Adis, you should leave the attribute table and colormap entries at their default values; otherwise, the results are not defined.
The ability to use generic display attributes is provided by a number of call-by-name library routines. These routines are explained in the following sections.
UNIX:
On UNIX, you can use generic attributes
with the COBCTRLCHAR
environment variable set to Y or y. However, the generic attributes
feature is not aware of any changes you make directly by sending sequences
to the terminal. Therefore, you should avoid making any changes to
attributes directly, or the results on screen are unpredictable.
Several call-by-name library routines are available to help you handle display attributes.
They can help you:
16-bit:
On the 16-bit COBOL system to use the generic display attributes, you
must place the genatt program in the install section of your
trigger's configuration file. The call-by-name library routines for
display attributes will only work if this has been done.
16-bit:
The routines for creating and handling virtual color maps are available
on the 16-bit COBOL system only.
The parameters listed below contain predefined parameters for the display attribute call-by-name routines. You can include these parameters in your application to simplify the coding process.
01 attribute-information. 03 display-class pic x comp-x. 03 colormap-size pic xx comp-x. 03 colormap-flags pic x comp-x. 03 bits-per-gun pic x comp-x. 01 table-start pic xx comp-x. 01 table-count pic xx comp-x. 01 attribute-index pic x occurs a times. 01 attribute-value occurs a times. 03 foreground-color-attribute pic xxxx comp-x. 03 background-color-attribute pic xxxx comp-x. 03 character-attribute pic x comp-x. 03 filler pic xxx. 01 color-attribute pic xxxx comp-x occurs c times. 01 color-name. 03 color-name-length pic x comp-x value n. 03 color-name-buffer pic x(n). 01 rgb-values occurs c times. 03 red-value pic xx comp-x. 03 green-value pic xx comp-x. 03 blue-value pic xx comp-x. 03 filler pic xx. 01 non-exact-match pic x comp-x occurs c times.
where:
a |
is the number of entries in your attribute table. |
c |
is the number of entries in the colormap. |
n |
is the maximum length in characters of a color name. |
If you use these parameters in your program, be sure to change the subscripted items to agree with the size of your tables. See the section Multiple Operations for information about the use of subscripted items.
The following routines return information about your current environment.
CBL_SCR_GET_ATTR_INFO
Retrieves information about the current environment.
It is useful for your program to know some details of its current environment. This routine returns the following:
CBL_SCR_NAME_TO_RGB
Translates the name of a color (alpha string) to RGB values.
When you ask to display a color, you must describe it as proportions of red, green, and blue (RGB) - for example, RGB = x"7F00", x"0000", x"7F00" gives a magenta color.
Using CBL_SCR_NAME_TO_RGB, your program can send one of a fixed set of color names and get the RGB values back. These values can then be used in calls requesting the color. This is useful because:
This last point is important; for example, if one programmer decided that magenta was x"7F00", x"0000", x"7F00" and another that magenta was x"7EFF", x"0000", x"7EFF", two different entries could be created in the colormap. This is a duplication, using up colormap entries which might be needed for genuinely different colors.
This function is completely separate from the other generic attributes functions. The names and RGB values are a fixed part of the run-time system and the range of choices can vary between environments. On UNIX environments, the information used for this call is found in the file $COBDIR/rgb.txt in this format:
redvalue greenvalue bluevalue colorname [#comment]
Example
The following example shows how to convert a color name to an RGB value:
01 rgb-values occurs n times. 03 red-value pic xx comp-x. 03 green-value pic xx comp-x. 03 blue-value pic xx comp-x. 03 filler pic xx. 01 color-name. 03 color-name-length pic x comp-x. 03 color-name-buffer pic x(20). ... move 4 to color-name-length move "cyan" to color-name-buffer call "CBL_SCR_NAME_TO_RGB" using color-name rgb-values(1) ...
Your program can use the following routines to manipulate the current environment's colormap.
CBL_SCR_ALLOCATE_COLOR
Returns the index in the system default colormap for each of one or more colors that you describe as RGB values.
You supply a table of colors described as RGB values in rgb-values
and specify the number of entries the table has in table-count
.
If you set non-exact-match
to nonzero, near matches
are considered to be acceptable, saving processing time.
See the section Parameter Listing for the format of the data items.
CBL_SCR_ALLOCATE_COLOR returns a corresponding table of colormap indexes
in color-attribute
, and a corresponding table of
information about the match in non-exact-match
.
For each color:
Otherwise the nearest match is found and its index is returned.
non-exact-match
tells you whether the index
returned corresponds to an exact match or not. If it is equal to 0, the
match was exact. Otherwise, it was the nearest match. The returned table rgb-values
holds the values
that the RTS used during its search, truncated appropriately for the
environment, rather than the values of the nearest match in the colormap.
table-count
tells you how far down your table of
requested colors the routine got - usually the number of entries in your
table. If any error occurs, further table entries are not attempted.
You cannot change a specific entry in the system colormap as you can with a virtual colormap.
Example
The following example shows how to find colors in the system colormap:
... * look for one color move 1 to table-count * previously set up rgb-values(1) using CBL_SCR_NAME_TO_RGB call "CBL_SCR_ALLOCATE_COLOR" using table-count rgb-values(1) color-attribute(1) non-exact-match(1) move color-attribute(1) to ... if non-exact-match(1) = 0 ...
CBL_SCR_CREATE_VC
Copies the current system colormap into another colormap, the virtual colormap, and uses this new colormap.
You can use the CBL_SCR_CREATE_VC routine to write specifically to any location in the virtual colormap. You can also destroy the virtual colormap (using the CBL_SCR_DESTROY_VC routine), reinstating the system colormap. While a virtual colormap is in existence, it is always used instead of the system colormap.
A unique feature is that by changing an entry, you can recolor all screen areas that use that colormap entry (except on UNIX character-based screens and emulators).
16-bit:
This routine is available on the 16-bit COBOL system only.
Stores one or more colors as RGB values in specified virtual colormap entries.
This function is only available after you have created a virtual colormap, using the CBL_SCR_CREATE_VC routine.
You specify:
rgb-values
.
color-attribute
.
table-count
.
CBL_SCR_ALLOCATE_VC_COLOR returns confirmation that these colormap locations now contain the colors you requested.
16-bit:
This routine is available on the 16-bit COBOL system only.
CBL_SCR_DESTROY_VC
Erases the virtual colormap and reinstates the system colormap as it was when CBL_SCR_CREATE_VC was used.
No parameters are needed.
16-bit:
This routine is available on the 16-bit COBOL system only.
CBL_SCR_QUERY_COLORMAP
Retrieves the RGB values of one or more colormap entries whose indexes you specify.
The colormap interrogated is the one currently in use; that is, the virtual colormap if one exists, otherwise the system colormap.
You supply a table of one or more indexes to the colormap, indicating the entries to query and specify how many entries your table has.
CBL_SCR_QUERY_COLORMAP returns a corresponding table of RGB values for each index.
Your program can use the following routines to manipulate the attribute table.
CBL_SCR_SET_ATTRIBUTES
Defines the character attribute code, foreground color indexes and background color indexes associated with one or more COBOL attribute values (attribute table indexes).
You supply:
CBL_SCR_SET_ATTRIBUTES returns confirmation that these attribute table locations now contain the attributes you requested.
CBL_SCR_GET_ATTRIBUTES
Retrieves the character attribute code, foreground color indexes, and background color indexes associated with a particular COBOL attribute value (attribute table index).
You supply a table of one or more indexes to the attribute table, indicating the entries to query and specify how many entries the table has.
CBL_SCR_GET_ATTRIBUTES returns a corresponding table of character attribute, foreground color, and background color for each index.
As an example, here is how you display a character in red, blinking, and on a cyan background.
If you want to display characters, you can use an RTS routine such as CBL_WRITE_SCR_CHATTRS. One of the pieces of information needed with this call is an attribute byte, so you need to perform at least two tasks first:
First, you need to find out how red and cyan are represented in RGB values on the current environment. The RTS translates a range of color names, sent as an alpha string, into RGB format using CBL_SCR_NAME_TO_RGB. After making two calls to CBL_SCR_NAME_TO_RGB, you could find that red is RGB x"7F00", x"0000", x"0000" and cyan is RGB x"0000", x"7F00", x"7F00".
Next, you need to find out where these colors, or their nearest matches, lie in the colormap of the current environment. CBL_SCR_ALLOCATE_COLOR uses RGB values to search the table, and return the colormap index of the best match. If your current environment is DOS on an IBM PC, the calls return 3 in response to RGB x"0000", x"7F00", x"7F00" (cyan), and 4 in response to RGB x"7F00", x"0000", x"0000" (red).
By referring to the section Character Attribute Codes later in this chapter, you can see that the code for a blinking character (with no other character attributes) is 8 (bit 3 on, all others off).
Now you are ready to specify an entry in the attribute table, using the CBL_SCR_SET_ATTRIBUTES routine . You can choose any convenient entry between 0 and 255 - for example, 42. Make the call using:
Now whenever you supply the attribute 42 with a call to write to the screen, you get a red foreground blinking on a cyan background.
If you recompile the program for another environment, you could still expect this behavior, because:
In practice, you need data items defined in Working-Storage Section of your program to send with the calls. See the section Parameter Listing earlier in this chapter for examples of the necessary definitions.
Where there are group items, they can be set to only one occurrence if
desired, and table-count
can be assigned the value
1. For more information about multiple operations, see the section Multiple
Operations.
The following operations can be carried out for several entries in the attribute table or the colormap using a single call. The entries need not be contiguous.
To do this, you need to set up the parameters passed on the call, except
table-count
, as group items in the Working-Storage
Section of your program. See the section Parameter Listing for
definitions of the data items. Bear in mind the following points:
attribute-index
and attribute-value
have a one-to-one correspondence and can be seen as two columns of a
single table. attribute-value
indexes the
attribute table.
color-attribute
, rgb-values
and non-exact-match
have a one-to-one
correspondence, and can be seen as three columns of a single table.
color-attribute
indexes the colormap.
table-count
.
If the routine fails to implement all the entries, a reduced value is
returned in table-count
. The routine finishes when
the first error is encountered.
Your tables could potentially have many occurrences. For example, you might set up several different colormap value sets in one table, putting them into operation by altering the subscript before making the call.
When you make a call:
table-count
equal to n, the number
of operations you want to perform, and hence the number of entries in
your table(s) that you want to use.
x+n must be less than N+1 (N+1 because the first of the n entries is number x).
Remember that table-count
and the subscript
(offset) refer to locations in the table parameters that you are sending
with the call, not locations in the colormap or attribute table.
If an error occurs (for example, you tried to reference a nonexistent
location in the attribute table or colormap), table-count
is reduced to the number of operations actually performed when it is
returned. Since the entries in your parameter tables are used
sequentially, and the first error finishes the call, you can calculate
which entries have been successfully used.
As an example, suppose that you need to perform two routines quite frequently, one of which returns the RGB values of the even-numbered entries in an 8-entry colormap, the other of which returns the RGB values of the odd-numbered entries.
color-attribute
is the table to pass with a call
to specify which locations in the colormap to look in. Since you can
perform operations using contiguous sections of this table, store values
in it as follows:
move 1 to color-attribute(1) move 3 to color-attribute(2) move 5 to color-attribute(3) move 7 to color-attribute(4) move 2 to color-attribute(5) move 4 to color-attribute(6) move 6 to color-attribute(7) move 8 to color-attribute(8).
Now make a call to look at the even entries:
... * specify the number of operations: four move 4 to table-count. * specify start location in color-attribute table: five move 5 to table-start. call "CBL_SCR_QUERY_COLORMAP" using table-count color-attribute(table-start) rgb-values(table-start) * if table-count is not 4, then perform error-routine, otherwise * continue. perform look-at-rgb-values-5-thru-8 ...
The RTS attribute table is initialized so that its default settings produce correct results when used with the earlier attribute code system used by previous Micro Focus COBOL systems. This means that you do not need to change existing programs to run them with the new RTS.
This section describes this earlier standard. The system uses specific bits of a single byte to produce a limited range of character attributes and foreground and background colors.
DOS, Windows and OS/2:
For DOS, Windows and OS/2, the following list shows the structure of
the attribute byte for a PC with a monochrome display. The effects of
setting (making equal to 1) and unsetting (making equal to 0) these bits
in the attribute byte are shown. The bits are shown in the order of most
significant to least significant (that is, 7-0).
Bit |
Attribute |
---|---|
7 | Blink |
6-4 | Turns off display or sets reverse video |
3 | Intensity |
2-0 | Normal or underline select |
where bits 0, 1, 2, 4, 5, and 6 are used together as follows:
bits 6, 5, 4
all set |
bits 6, 5, 4
all unset |
bits 6, 5, 4;
other settings |
|
bits 2, 1 ,0
unset |
reverse video | no display | normal display |
bits 2, 1 unset bit 0 set | underlined display | ||
all other
settings |
normal display |
For example, when bit 7 is set to 1, blinking is on, and when bit 3 is set to 1, text is displayed at high intensity.
Normal text on a monochrome display (that is nonhighlighted text in a black background) can be obtained by a number of different bit settings, since several bits that are used to control color are ignored by the monochrome display. However, only one combination produces this normal text on both monochrome and color displays:
Normal setting = 0 0 0 0 0 1 1 1 (decimal = 07, hex = x"07")
To ensure consistent results from programs that are used on both color and monochrome displays, you should ensure that you use this setting to achieve normal text.
DOS, Windows and OS/2:
For DOS, Windows and OS/2, the following list shows the structure of
the attribute byte for a PC with a color display. The effects of setting
and unsetting these bytes are shown.
Bit |
Attribute |
---|---|
7 | Blink |
6-4 | Background color |
3 | Intensity |
2-0 | Foreground (text) color |
where bits 6, 5, and 4 control the background color as follows:
Bits 6 5 4 |
Attribute |
---|---|
0 0 0 | Black |
0 0 1 | Blue |
0 1 0 | Green |
0 1 1 | Cyan |
1 0 0 | Red |
1 0 1 | Magenta |
1 1 0 | Brown |
1 1 1 | Light gray |
and where bits 2, 1, and 0 control the foreground (text) color in conjunction with bit 3 as follows:
Bits
2 1 0 |
Bit 3 unset |
Bit 3 set |
---|---|---|
0 0 0
0 0 1 0 1 0 0 1 1 1 0 0 1 0 1 1 1 0 1 1 1 |
Black
Blue Green Cyan Red Magenta Brown Light gray |
Dark gray
Light blue Light green Light cyan Light red Light magenta Yellow White |
These codes are used in all environments and are translated accordingly by the RTS.
Bit |
Meaning when set |
---|---|
7 | Reserved |
6 | Dimmed |
5 | Left line |
4 | Overline |
3 | Blink |
2 | Reverse video |
1 | Underline |
0 | Bold |
There are two ways of making characters and their associated attributes appear on the screen:
display "hello" at 1540 with background-color red-value foreground-color blue-value blink.
call "CBL_WRITE_SCR_CHATTRS" using screen-position character-buffer attribute-buffer string-length.
Call-by-name routines give you much more comprehensive control over the display. For example, you can:
Note: If you want to use Adis, you should leave the attribute table and colormap entries at their default values, otherwise the results are not defined.
The screen attribute allows you to specify an attribute associated with each character position on the screen. You can define areas of the screen as having different attributes. Whenever a character is displayed on the screen, it has the attribute associated with that position on the screen.
The user attribute is associated with the whole screen. All the characters that are displayed have the same attribute. To use this feature, a program must specifically enable the user attribute. If anything other than the normal display (system dependent - typically white or light green text on a black background) is required, the setting must also be explicitly changed. If a program uses the user attribute, it must be enabled for the whole duration of the program.
The user attribute overrides any screen attributes that you have already defined. Therefore, any text that is already displayed takes the user attribute rather than any screen attributes that are already defined, for any period during which the user attribute is enabled.
This section contains information about writing new programs. It presents information you will need if you are writing new programs regardless of whether or not they use generic attributes.
If your program does not set up a generic attribute table, a default attribute table is used, in order to provide backward compatibility. On DOS, Windows, and OS/2 this is the IBM-PC attribute table; on UNIX, it is a monochrome table that emulates the attribute byte in the section Character Attribute Codes.
Any new program you write to be portable across environments must use generic attributes to set up an attribute table, or only Enhanced ACCEPT/DISPLAY statements or Screen Section to handle its display. This section describes the process your program must perform to set up a basic attribute table that should be sufficient for most programs.
Your program must perform the following steps:
Having completed these three steps your program has defined an attribute table that can be used to create portable applications.
The following routines are available to help you use attributes in your character user interfaces, independent of environment:
CBL_GET_SCR_GRAPHICS | Get graphics characters |
CBL_GET_SCR_LINE_DRAW | Get line drawing characters |
CBL_SCR_ALLOCATE_COLOR | Allocate color for RGB value |
CBL_SCR_ALLOCATE_VC_COLOR | Allocate color in virtual colormap |
CBL_SCR_CREATE_VC | Create virtual colormap |
CBL_SCR_DESTROY_VC | Destroy virtual colormap |
CBL_SCR_GET_ATTR_INFO | Get attribute information |
CBL_SCR_GET_ATTRIBUTES | Get attribute value |
CBL_SCR_NAME_TO_RGB | Convert color name to RGB value |
CBL_SCR_QUERY_COLORMAP | Query colormap entry |
CBL_SCR_RESTORE | Restore attribute table |
CBL_SCR_RESTORE_ATTRIBUTES | Restores an area of the screen |
CBL_SCR_SAVE | Save an area of the screen |
CBL_SCR_SAVE_ATTRIBUTES | Save attribute table |
CBL_SCR_SET_ATTRIBUTES | Set attribute value |
These routines are described here.
Finds an entry in the colormap for each of one or more given RGB values.
call "CBL_SCR_ALLOCATE_COLOR" using table-count RGB-values color-attribute non-exact-match returning status-code
table-count
pic
x(2) comp-x.
RGB-values
Group
item, occurs n times, defined as:
red-value
pic
x(2) comp-x.
green-value
pic
x(2) comp-x.
blue-value
pic
x(2) comp-x.
filler
pic
x(2).
color-attribute
pic
x(4) comp-x occurs n times.
non-exact-match
pic
x comp-x occurs n times.
status-code
See
Key in the Preface
table-count |
The number of colors requested. |
RGB-values |
The table of color(s) to search for or add to the colormap. |
color-attribute |
The table of indexes to the colormap corresponding to the colors requested. This can be an existing colormap entry, or an unallocated read-write colormap entry set to the requested color. |
non-exact-match |
The table of flags indicating whether or not the corresponding occurrence of color-attribute represents an exact match. Zero if the match was exact, otherwise nonzero. |
table-count |
The number of colors successfully allocated. This is normally the number requested but is less if the call was not entirely successful. |
RGB-values |
The table of RGB values actually used during the search, truncated to suit the environment. |
filler |
Unused. |
The RGB value can either be specified as a literal or be obtained using a call to the CBL_SCR_NAME_TO_RGB routine. The algorithm for determining the nearest match is environment-defined.
CBL_SCR_NAME_TO_RGB
Sets one or more specified virtual colormap entries to the RGB values supplied.
call "CBL_SCR_ALLOCATE_VC_COLOR" using table-count color-attribute RGB-values returning status-code
table-count
pic
x(2) comp-x.
color-attribute
pic
x(4) comp-x occurs n times.
RGB-values
Group
item, occurs n times, defined as:
red-value
pic
x(2) comp-x.
green-value
pic
x(2) comp-x.
blue-value
pic
x(2) comp-x.
filler
pic
x(2).
status-code
See
Key in the Preface
table-count |
The number of colors to allocate. |
color-attribute |
The table of indexes to the locations in the virtual colormap in which to store the specified RGB values. |
RGB-values |
The table of color(s) to add to the virtual colormap. |
table-count |
The number of colors successfully allocated. This is normally the number requested but is less if the call was not entirely successful. |
RGB-values |
The table of RGB values actually used during the search, truncated to suit the environment. |
filler |
Unused. |
The RGB values can either be specified as a literal or be obtained using a call to the CBL_SCR_NAME_TO_RGB routine.
CBL_SCR_NAME_TO_RGB
Creates a virtual colormap and copies the contents of the system colormap to it.
call "CBL_SCR_CREATE_VC" returning status-code
status-code
See
Key in the Preface
None
None
The run-time system can only have one virtual colormap, and it is used in preference to the system colormap as long as it exists.
Destroys a virtual colormap, causing the run-time system to revert to using the system colormap.
call "CBL_SCR_DESTROY_VC" returning status-code
status-code
See
Key in the Preface
None
None
Returns information about the attribute system for the environment.
call "CBL_SCR_GET_ATTR_INFO" using attribute-info returning status-code
attribute-info
Group
item defined as:
class
pic
x comp-x.
colormap-size
pic
x(2) comp-x.
colormap-flags
pic
x comp-x.
bits-per-gun
pic
x comp-x.
status-code
See
Key in the Preface
None
class |
The class of the environment:
|
||||||||||
colormap-size |
Number of entries on the colormap. | ||||||||||
colormap-flags |
|
||||||||||
bits-per-gun |
Number of significant bits of the RGB values that are actually used to drive the hardware. A value of zero indicates that the number of bits is unknown for the environment. If different guns have different numbers of significant bits the lowest number of bits is used. |
Gets the character attribute code, and foreground and background colormap indexes for one or more entries in the attribute table.
call "CBL_SCR_GET_ATTRIBUTES" using table-count attribute-index attribute-value returning status-code
table-count
pic
x(2) comp-x.
attribute-index
pic
x comp-x occurs n times.
attribute-value
Group
item, occurs n times, defined as:
foregrnd-index
pic
x(4) comp-x.
backgrnd-index
pic
x(4) comp-x.
character-attr
pic
x comp-x.
filler
pic
x(3)
status-code
See
Key in the Preface
table-count |
The number of attribute table entries to query. |
attribute-index |
The table of indexes of the entries to query. |
table-count |
The number of entries successfully queried. This is normally the number requested but is less if the call was not entirely successful. |
attribute-value |
The table of attribute values corresponding to the indexes supplied. |
filler |
Unused. |
Converts a single named color into an RGB value.
call "CBL_SCR_NAME_TO_RGB" using color-name RGB-values returning status-code
color-name
Group
item defined as:
color-name-len
pic
x comp-x.
color-name-buf
pic
x(n).
RGB-values
Group
item defined as:
red-value
pic
x(2) comp-x.
green-value
pic
x(2) comp-x.
blue-value
pic
x(2) comp-x.
filler
pic
x(2).
status-code
See
Key in the Preface
color-name-len |
The number of characters in the name. |
color-name-buf |
The color name to be converted. |
RGB-values |
The RGB value to which the named color is converted. |
filler |
Unused. |
Returns the RGB value for one or more colormap entries.
call "CBL_SCR_QUERY_COLORMAP" using table-count color-attribute RGB-values returning status-code
table-count
pic
x(2) comp-x.
color-attribute
pic
x(4) comp-x occurs n times.
RGB-values
Group
item, occurs n times, defined as:
red-value
pic
x(2) comp-x.
green-value
pic
x(2) comp-x.
blue-value
pic
x(2) comp-x.
filler
pic
x(2).
status-code
See
Key in the Preface
table-count |
The number of entries to query. |
color-attribute |
The table of one or more colormap indexes to query. |
RGB-values |
The table of RGB values corresponding to the table indexes. |
table-count |
The number of entries successfully queried. This is normally the number requested but is less if the call was not entirely successful. |
Restores an area of the character-mode screen previously saved with a call to the CBL_SCR_SAVE call-by-name routine.
call NoReturnCode "CBL_SCR_RESTORE" using by value flags handle.
flags
pic
x(4) comp-5.
handle
usage
pointer.
Because the flags
parameter is passed BY VALUE, it
may be specified as a numeric literal. For example, "BY VALUE 0 SIZE
4".
This call returns no status value. Therefore, it must be called using a suitable call-convention (as suggested in the syntax description) that you have defined in the special-names section. A suitable convention for this purpose is 4.
CBL_SCR_RESTORE has advantages over writing areas of the screen directly:
flags |
Currently, this must always be zero. |
handle |
A "save-handle" previously returned by a call to the CBL_SCR_SAVE call-by-name routine. This handle can be NULL, in which case the call does nothing. |
handle |
Is untouched, but invalid. It must not be passed again to CBL_SCR_RESTORE unless it has subsequently been re-assigned a valid "save-handle" by a further call to the CBL_SCR_SAVE routine. |
We recommend that you set this pointer to NULL immediately on return from CBL_SCR_RESTORE. | |
The area of the screen saved when the call to
CBL_SCR_SAVE which returned handle was made is
written, in the same position, to the screen. |
It is valid to change the mode of the screen (for example, switch the screen to 132-column mode) after saving an area of the screen with CBL_SCR_SAVE providing that the mode is restored to the previous setting before calling CBL_SCR_RESTORE. Failure to do so will result in undefined results.
Restores the attribute table to the saved values that are associated with the specified buffer handle.
call "CBL_SCR_RESTORE_ATTRIBUTES" using handle returning status-code
handle
pointer.
status-code
See
Key in the Preface
handle |
The handle returned on the associated call to CBL_SCR_SAVE_ATTRIBUTES. |
None
This routine restores the COBOL attribute table to the saved values that are associated with handle. Resources that have been used to save the table are freed.
If the handle is null, the call is ignored. If the handle is invalid or is a handle to a table that has already been restored, results are undefined.
On return, handle is set to null in order to prevent multiple restores of the same attribute table settings.
CBL_SCR_SAVE_ATTRIBUTES
Saves away an area of the screen (text and attributes) for subsequent restoration.
call "CBL_SCR_SAVE" using by value flags top-line bottom-line returning handle.
flags
pic
x(4) comp-5.
top-line
pic
x(4) comp-5.
bottom-line
pic
x(4) comp-5.
handle
usage
pointer.
Because the three parameters are passed BY VALUE, any or all of them may be specified with numeric literals. For example, "BY VALUE 12 SIZE 4".
CBL_SCR_SAVE has advantages over reading areas of the screen directly:
flags |
Currently, this MUST ALWAYS be zero. |
top-line |
The line nearest the top of the screen of the area to be saved. Line 1 is the top line. |
bottom-line |
The line nearest the bottom of the screen of the area to be saved. Line 1 is the top line. |
The area between the top-line and bottom-line INCLUSIVE is saved. Therefore, if top-line and bottom-line are equivalent, a single line of the screen is saved.
Note that specifying zero as a top-line or bottom-line means that parameter will be considered to be the last line on the screen. This saves you from having to know the size of the screen if, for instance, you wished to save the whole screen.
The logical value of top-line must be equal or less than the logical value of bottom-line.
handle |
Will contain a "save-handle" which can be subsequently passed to the CBL_SCR_RESTORE call-by-name routine, or will have value NULL, meaning that the save operation could not be performed (Bad parameters, or possibly out of memory). |
If handle
is not subsequently passed to the "CBL_SCR_RESTORE"
routine, any core memory that may have been allocated to save the screen
information in will be lost. Repeated failure to call "CBL_SCR_RESTORE"
with handles returned from "CBL_SCR_SAVE" will therefore result
in a memory leak.
It is invalid to pass handle
to any routine other
than "CBL_SCR_RESTORE".
To save the screen in its entirety, whatever its size:
call "CBL_SCR_SAVE" using by value 0 size 4 1 size 4 0 size 4 returning handle.
To save just the last line of the screen:
call "CBL_SCR_SAVE" using by value 0 size 4 0 size 4 0 size 4 returning handle.
To save the top three lines of the screen:
call "CBL_SCR_SAVE" using by value 0 size 4 1 size 4 3 size 4 returning handle.
Saves the current settings of the attribute table.
call "CBL_SCR_SAVE_ATTRIBUTES" using handle returning status-code
handle
pointer.
status-code
See
Key in the Preface
None
handle |
The handle of the internal buffer used to save the attributes. |
This routine saves the current COBOL attribute table in an internal buffer. The handle is set to a value that identifies this buffer, and no meaning should be attached to the value of handle.
CBL_SCR_RESTORE_ATTRIBUTES
Defines the character attribute, and foreground and background colormap indexes associated with each of one or more COBOL attribute values (attribute table indexes).
call "CBL_SCR_SET_ATTRIBUTES" using table-count attribute-index attribute-value returning status-code
table-count
pic
x(2) comp-x.
attribute-index
pic
x comp-x occurs n times.
attribute-value
Group
item, occurs n times, defined as:
foregrnd-index
pic
x(4) comp-x.
backgrnd-index
pic
x(4) comp-x.
character-attr
pic
x comp-x.
filler
pic
x(3).
status-code
See
Key in the Preface
table-count |
The number of attributes to set. |
attribute-index |
The table of indexes in the attribute table. |
attribute-value |
The table of attribute descriptions corresponding to the table of indexes. |
table-count |
The number of attributes successfully set. This is normally the number requested but is less if the call was not entirely successful. |
filler |
Unused. |
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
IBM PC Display Attributes |