| 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:
The ability to use generic display attributes is provided by a number of call-by-name library routines. These routines are explained in later sections.
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, 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 (run-time system).
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 run-time system 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 run-time system call-by-name routines discussed in this chapter.
When a program calls the run-time system with a request to write an attribute to the screen, the call passes an attribute byte. The run-time system 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.
Several call-by-name library routines are available to help you handle display attributes.
They can help you:
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. You can declare the variables for these parameters in three different ways, using:
The variables in the OCCURS dimensions in the parameter blocks below are:
a |
Number of entries in your attribute table. |
c |
Number of entries in the colormap. |
n |
Maximum length in characters of a color name. |
If you use these paramter blocks 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.
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 comp-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.
01 attribute-information.
03 display-class cblt-x1-compx.
03 colormap-size cblt-x2-compx.
03 colormap-flags cblt-x1-compx.
03 bits-per-gun cblt-x1-compx.
01 table-start cblt-x2-compx.
01 table-count cblt-x2-compx.
01 attribute-index cblt-x1-compx occurs a times.
01 attribute-value occurs a times.
03 foreground-color-attribute cblt-x4-compx.
03 background-color-attribute cblt-x4-compx.
03 character-attribute cblt-x1-compx.
03 filler pic xxx.
01 color-attribute cblt-x4-compx occurs c times.
01 color-name.
03 color-name-length cblt-x1-compx value n.
03 color-name-buffer pic x(n).
01 rgb-values occurs c times.
03 red-value cblt-x2-compx.
03 green-value cblt-x2-compx.
03 blue-value cblt-x2-compx.
03 filler cblt-x1-compx occurs 2 times.
01 non-exact-match cblt-x1-compx occurs c times.
01 attribute-information cblt-generic-attr-information.
01 table-start cblt-x2-compx.
01 table-count cblt-x2-compx.
01 attribute-index cblt-x1-compx occurs a times.
01 attribute-value cblt-generic-attr-value occurs a times.
01 color-attribute cblt-x4-compx occurs c times.
01 color-name.
03 color-name-length cblt-x1-compx value n.
03 color-name-buffer pic x(n).
01 rgb-values cblt-generic-attr-rgb-values occurs c times.
01 non-exact-match cblt-x1-compx occurs c times.
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/etc/rgb.txt in this format:
redvalue greenvalue bluevalue colorname [#comment]
The following example shows how to convert a color name to an RGB value:
01 rgb-values cblt-generic-attr-rgb-values occurs n times.
01 color-name.
03 color-name-length cblt-x1-compx.
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 run-time system 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.
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_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 run-time system 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 run-time system 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 run-time system 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 run-time system.
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.
These codes are used in all environments and are translated accordingly by the run-time system.
| 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; 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_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 |
Note: Screen output should be initialized before using these
routines; for example, by using display spaces upon crt.
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. The call-by-number library routines (those of the form x"XX" do not use CALL prototypes.
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.
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 |
cblt-x2-compx. | ||||||||
RGB-values |
A group item predefined as cblt-generic-attr-rgb-values,
containing the following subordinate items:
|
||||||||
color-attribute |
cblt-x4-compx occurs n times. | ||||||||
non-exact-match |
cblt-x1-compx 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.
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 |
cblt-x2-compx. | ||||||||
color-attribute |
cblt-x4-compx occurs n times. | ||||||||
RGB-values |
A group item predefined as cblt-generic-attr-rgb-values,
containing the following subordinate items:
|
||||||||
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.
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 |
A group item predefined as clbt-gai-display-class,
containing the following subordinate items:
|
||||||||
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 |
cblt-x2-compx. | ||||||||
attribute-index |
cblt-x1-compx occurs n times. | ||||||||
attribute-value |
A group item predefined as cblt-generic-attr-value,
containing the following subordinate items:
|
||||||||
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 |
A group item containing the following
subordinate items:
|
||||||||
RGB-values |
A group item predefined as cblt-generic-attr-rgb-values,
containing the following subordinate items:
|
||||||||
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 |
cblt-x2-compx. | ||||||||
color-attribute |
cblt-x4-compx occurs n times. | ||||||||
RGB-values |
A group item predefined as cblt-generic-attr-rgb-values,
containing the following subordinate items:
|
||||||||
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 cblt-x4-comp5. handle cblt-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 cblt-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.
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 cblt-x4-comp5. top-line cblt-x4-comp5. bottom-line cblt-x4-comp5. handle cblt-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 |
Contains either a "save handle", which can be subsequently passed to the CBL_SCR_RESTORE call-by-name routine, or the value NULL, meaning that the save operation could not be performed (because of bad parameters, or possibly lack 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 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.
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 |
cblt-x2-compx. | ||||||||
attribute-index |
cblt-x1-compx occurs n times. | ||||||||
attribute-value |
A group item, containing the following
subordinate items:
|
||||||||
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 © 2000 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 |