HP 3000 Manuals HP 3000 Manuals
Operation
This section gives you general information about Panels.
The Call Interface
You call the Panels module by using the following CALL statement in your
COBOL program:
call "PANELS" using panels-parameter-block [text-buffer]
[attribute-buffer]
where:
panels-parameter- is an 01 level item containing all the fields you
block define when you are working with Panels. The
definitions for this group item are provided in the
COPY-file panlink.cpy which is supplied with this
COBOL system. You never need to change panlink.cpy,
instead, your program moves mnemonics to certain data
items in panlink.cpy to specify what function Panels
is to perform.
text-buffer contains text to be included in a panel. It must be
defined in the Working-Storage Section of your
program.
attribute-buffer contains attributes to be included in a panel. It
must be defined in the either the Working-Storage or
Linkage Section of your program.
You must include panels-parameter-block in all calls to Panels. You
include the text-buffer and attribute-buffer parameters in the CALL
statement only if you are writing to, reading from, or scrolling a panel.
When you specify text-buffer, it must always be the second parameter in
the call. attribute-buffer must be the third parameter in the call.
Therefore, if you want to specify attributes without specifying text, you
must set up a dummy parameteras the second parameter in the call. The
dummy parameter can be any variable. The syntax to specify a dummy
parameter is as follows:
call "PANELS" using panels-parameter-block dummy attribute-buffer
Text and Attributes for a Panel
You can specify text characters for a panel in two ways:
*
Define text-buffer in the Working-Storage Section of your program
and call Panels using text-buffer as a parameter. This method can
be used to fill an area with different characters.
* Specify a value for PPB-Fill-Character in the parameter block.
This method can be used to fill an area with the same character.
You can specify attributes for a panel in two ways:
* Define attribute-buffer in the Working-Storage Section of your
program and call Panels using attribute-buffer as a parameter.
This method can be used to fill an area with different attributes.
* Specify a value for PPB-Fill-Attribute in the parameter block.
This is used to fill an area with the same attribute.
Each attribute is one byte long and is specific to your machine. See the
appendix Display Attributes for more information about the attribute
bytes used in the IBM-PC environment.
The Panels Parameter Block
The Panels parameter block, shown below, is made up of fields that you
initialize to execute a particular function within Panels. You must make
sure that you define all fields relevant to a function before calling
Panels. Each field is described later in this section, and the fields
relevant to a particular function are given in the section Panels
Functions. For your convenience, the parameter block is in the COPY-file
panlink.cpy, provided with the Panels software, and you can use the COPY
statement to include it in your program. See your Language Reference for
details of the COPY statement.
01 Panels-Parameter-Block.
03 PPB-Function PIC 9(2) COMP.
03 PPB-Status PIC 9(2) COMP.
03 PPB-Panel-ID PIC 9(4) COMP.
03 PPB-Panel-Width PIC 9(4) COMP.
03 PPB-Panel-Height PIC 9(4) COMP.
03 PPB-Visible-Width PIC 9(4) COMP.
03 PPB-Visible-Heigh PIC 9(4) COMP.
03 PPB-First-Visible-Co PIC 9(4) COMP.
03 PPB-First-Visible-Row PIC 9(4) COMP.
03 PPB-Panel-Start-Column PIC 9(4) COMP.
03 PPB-Panel-Start-Row PIC 9(4) COMP.
03 PPB-Buffer-Offse PIC 9(4) COMP.
03 PPB-Vertical-Stride PIC 9(4) COMP.
03 PPB-Update-Group.
05 PPB-Update-Coun PIC 9(4) COMP.
05 PPB-Rectangle-Offset PIC 9(4) COMP.
05 PPB-Update-Start-Col PIC 9(4) COMP.
05 PPB-Update-Start-Row PIC 9(4) COMP.
05 PPB-Update-Width PIC 9(4) COMP.
05 PPB-Update-Height PIC 9(4) COMP.
03 PPB-Fill.
05 PPB-Fill-Character PIC X.
05 PPB-Fill-Attribute PIC X.
03 PPB-Update-Mask PIC X.
03 PPB-Scroll-Direction PIC 9(2) COMP.
03 PPB-Scroll-Count PIC 9(4) COMP.
The data items in panlink.cpy are explained in the sections below.
PPB-Function .
The function you want Panels to perform must be specified for every call.
You enter the value of the function, or its mnemonic, in this field.
Each function is described in the section Panels Functions. The
following list shows all Panels functions, giving their numbers,
mnemonics and brief descriptions.
Function Name Value Description
-------------------------------------------------------------
PF-Get-Screen-Info 0 Gets screen information.
PF-Set-Screen- 1 Sets screen backdrop.
Backdrop
PF-Redraw-Screen 2 Redraws screen.
PF-Create-Panel 3 Creates a panel.
PF-Shift-Panel 4 Moves and resizes a window.
PF-Get-Panel-Info 5 Returns information about a panel.
PF-Delete-Panel 6 Deletes a panel.
PF-Enable-Panel 7 Enables a panel.
PF-Disable-Panel 8 Disables a panel.
PF-Flush-Panel 9 Flushes part of a panel.
PF-Scroll-Panel 10 Scrolls part of a panel.
PF-Write-Panel 11 Writes to part of a panel.
PF-Read-Panel 12 Reads from part of a panel.
PF-Get-Panel-At- 13 Returns the identifying handle of
Position the panel at the specified position.
PPB-Status.
After every call, Panels returns a status value in PPB-Status to indicate
the success, or otherwise, of the call. The function was successfully
executed if PPB-Status contains 0. If Panels returns a value greater
than 0, an error occurred while Panels was trying to execute the
function. A full list of status values is given in the section Panels
Error Codes later in this chapter.
You are recommended to test the status field after every call to Panels.
PPB-Panel-ID .
When you create a panel, Panels returns an identifying handle in
PPB-Panel-ID. Each panel you create is given a unique handle. When
working with a specific panel, PPB-Panel-ID must contain the handle that
was returned when that panel was created. Failure to specify the correct
handle is a common cause of problems when using Panels.
You should not assume that Panels allocates any particular identifier to
a particular panel. Neither should you assume that the same identifier
is used for two different executions of the same program. Always use the
identifier returned by Panels when the panel was created.
PPB-Panel-Width .
Panel width is defined in columns. You specify the width of a panel, in
characters, in PPB-Panel-Width. The width of a panel cannot exceed 2000
characters.
Once you have created a panel, you cannot adjust its width.
PPB-Panel-Height .
Panel height is defined in rows. You specify the height of a panel, in
characters, in PPB-Panel-Width. The height of a panel multiplied by its
width cannot exceed 65535 characters. If it does, Panels returns error
code 6, PE-Panel-Too-Large.
Once you have created a panel, you cannot adjust its height.
PPB-Visible-Width .
You specify the width of a visible window, in columns, in
PPB-Visible-Width. This sets the number of columns that are initially
visible on screen when you enable a panel.
The width of a window cannot be wider than either the width of the panel
or the screen.
PPB-Visible-Height.
You specify the height of a visible window, in rows, in
PPB-Visible-Height. This sets the number of rows that are initially
visible on the screen when you enable the panel. The height of the
window cannot be greater than either the height of the panel or the
screen.
PPB-First-Visible-Col .
The value you specify for PPB-First-Visible-Col determines the position
of the window relative to the left edge of the panel. If you set
PPB-First-Visible-Col to 0, the left edge of the window is aligned with
the left edge of the panel.
PPB-First-Visible-Row .
The value you specify for PPB-First-Visible-Row determines the
position of the window relative to the top of the panel. If you set
First-Visible-Row to 0, the top of the window is aligned with the top of
the panel.
PPB-Panel-Start-Column .
The value you specify for PPB-Panel-Start-Column determines the left edge
of the visible window on the screen. If you set PPB-Panel-Start-Column
to 0, the visible window is aligned with the first column on the screen.
PPB-Panel-Start-Row.
The value you specify for PPB-Panel-Start-Row determines the top of the
visible window on the screen. If you set PPB-Panel-Start-Row to 0, the
visible window is aligned with the first row on the screen.
PPB-Buffer-Offset.
The value you specify for PPB-Buffer-Offset determines the position of
the first character to be found in the text buffer and/or the first
attribute to be found in the attribute buffer. A value of one indicates
the first byte in the buffer.
PPB-Vertical-Stride.
The value you specify for PPB-Vertical-Stride determines the distance, in
characters, between the start of one row and the start of the next row in
the text and/or attribute buffers. You must make sure that the buffers
contain enough data to fill the specified area as Panels assumes that
enough data has been supplied.
PPB-Update-Count .
This field specifies the number of characters to be updated within a
specified rectangle. You can choose to update an irregular-shaped area
of a rectangle by specifying values for both the PPB-Update-Count and
PPB-Rectangle-Offset fields. See PPB-Rectangle-Offset for an example of
updating an irregular shaped rectangle.
If you update an entire rectangle, you set this field to the product of
the value of PPB-Update-Width multiplied by PPB-Update-Height.
PPB-Rectangle-Offset.
This field specifies how many characters not to update within the
rectangle. The value you specify for PPB-Rectangle-Offset is the
position within the specified rectangle (defined by PPB-Update-Width and
PPB-Update-Height) at which you wish to start updating the panel. If
you intend to update the entire rectangle, you should set the
PPB-Rectangle-Offset field to 0.
You can choose to update an irregular-shaped area of a rectangle by
specifying values for both the PPB-Update-Count and PPB-Rectangle-Offset
fields.
For example, Figure 24-1 shows a panel 20 characters wide by 25 rows
deep.
If you want to update the unshaded part of the panel you have to use
PPB-Update-Count and PPB-Rectange-Offset to specify how many characters
are to be updated, and where the updating is to start:
1. 406 characters of the panel are to be updated (6 characters on the
fifth line and 20 full lines, each line being 20 characters wide)
by moving 406 to PPB-Update-Count.
2. Updating starts on the fifth line of the rectangle, beginning with
the fifteenth character, so you need to skip the first 94
characters of the rectangle (four lines of 20 characters each,
plus 14 characters of the fifth line). Start updating by moving
94 to PPB-Rectangle-Offset.
PPB-Update-Start-Col .
This field defines the position of the rectangle within the panel. It
defines the first column of the rectangle that is affected when you
update the panel. If you specify 0 for PPB-Update-Start-Col, the first
column to be updated is the leftmost column of the panel.
![[]](../../pic3k/M015153/FFN93c50.gif)
Figure 24-1: Updating Part of a Rectangle
PPB-Update-Start-Row.
This field defines the position of the rectangle within the panel. It
defines the first row of the rectangle that is affected when you update
the panel. If you specify 0 for PPB-Update-Start-Row, the first row to
be updated is the top row of the panel.
PPB-Update-Width.
This field defines the size, in lines, of the rectangle to update. The
number defined in this field is the number of columns that are affected
when you update a panel. If the width of the update area is wider than
the width of the panel, the area is reduced to the width of the panel.
PPB-Update-Height.
This field defines the size, in characters, of the rectangle to update.
You specify a value in this field to determine the number of rows that
are affected when you update a panel. If the height of the update area
is greater than the height of the panel, the area is reduced to the
height of the panel.
PPB-Fill-Character.
You use PPB-Fill-Character to define either the backdrop character for
the screen or a single character to fill any area of the screen not
covered by an enabled panel. The initial value for PPB-Fill-Character is
SPACE.
PPB-Fill-Attribute.
You use PPB-Fill-Attribute to define the attribute of the backdrop
character for the screen or the attribute associated with the single
character you specify to fill a designated area of a panel. The default
(initial) value for this field is x"07" on an IBM-PC; that is, white text
on a black background.
PPB-Update-Mask.
You use PPB-Update-Mask field to specify:
* Whether the screen is to be automatically updated.
* Whether text, attributes or both are to be updated.
* The location of the data to fill the specified area.
The update mask is a single byte value (PIC X). The individual bits of
this byte are defined for PF-Flush-Panel, PF-Scroll-Panel, PF-Write-Panel
and PF-Read-Panel as shown below:
Bit Meaning When Set
-------------------------------------------------------
7 Unused. Reserved for future use and must
be set to 0.
6 Unused. Reserved for future use and must
be set to 0.
5 Any update to the attributes in a panel is
to show on the screen immediately
(provided the panel is enabled). If this
bit is not set, the update does not show
on the screen until the next call to
PF-Flush-Panel is made.
4 Any update to the text in a panel is to
show on the screen immediately (provided
the panel is enabled). If this bit is not
set, the update does not show on the
screen till the next call to
PF-Flush-Panel is made.
3 The attributes in the specified area of a
panel are to be replaced by the attribute
specified in PPB-Fill-Attribute in
Panels-Parameter-Block. This bit is
mutually exclusive with bit 1; setting
bits 3 and 1 causes unpredictable results.
2 The text in the specified area of a panel
is to be replaced by the character
specified in the PPB-Fill-Character in
Panels-Parameter-Block. This bit is
mutually exclusive with bit 0; setting
bits 2 and 0 causes unpredictable results.
1 The attributes in the specified area are
to be replaced by the attributes provided
in the attribute buffer. When used, this
buffer must always be specified as the
third parameter in the call to Panels.
This bit is mutually exclusive with bit 3;
setting bits 1 and 3 causes unpredictable
results.
0 The text in the specified area is to be
replaced by the text provided in the text
buffer. When used, this buffer must
always be specified as the second
parameter in the call to Panels. This bit
is mutually exclusive with bit 2. Setting
bits 0 and 2 causes unpredictable results.
NOTE
* Bits are ordered with bit 7 as the most significant, or
first, and bit 0 as the least significant, or last.
* PF-Read-Panel uses only bits 0 and 1.
PPB-Scroll-Direction .
You use PPB-Scroll-Direction to specify the direction in which the text
and attributes in a panel are to be scrolled. The values associated with
the scroll direction are:
Value Direction
-------------------------------------------------
0 Up
1 Down
2 Left
3 Right
PPB-Scroll-Count.
You use PPB-Scroll-Count to specify the number of rows or columns you
want to scroll. If you scroll up or down (PPB-Scroll-Direction is set to
0 or 1), PPB-Scroll-Count specifies the number of rows to be scrolled.
If you scroll to the left or right (PPB-Scroll-Direction is set to 2 or
3), PPB-Scroll-Count specifies the number of columns to be scrolled.
Clipping
When a panel is created or the window is moved or resized using
PF-Shift-Panel, the size of the window specified is validated by Panels
and is reduced in size if a window of the specified size cannot be
created. This is known as clipping the height and/or width of the
window.
The window can be reduced in size for two reasons. The following
examples describe how the width of the window is affected, but
the height is affected in a similar way, but depending on the
values of PPB-Panel-Start-Row and PPB-First-Visible-Row instead of
PPB-Panel-Start-Column and PPB-First-Visible-Col:
1. PPB-Panel-Start-Column is too large. If the value of the start
column is such that a window of the specified size would be off
the right-hand edge of the screen, the width of the window is
reduced to fit on the screen.
For example, for a screen that is 80 characters wide, a window is
defined that is 40 characters wide (PPB-Visible-Width = 40). If
the window starts with the 60th character of the screen
(PPB-Panel-Start-Column = 60) the screen would have to be 100
characters wide for the entire window to fit on the screen.
Because the screen is only 80 characters wide, PPB-Visible-Width
is clipped by 20 characters (PPB-Visible-Width is reduced to 20).
2. PPB-First-Visible-Col is too large. If the value of the start
column within the panel is such that a window of the specified
size would be off the right-hand edge of the panel, the width of
the window is reduced so that it is completely in the panel.
For example, if a panel has been created with a width
of 40 (PPB-Panel-Width = 40), and a window width of 30
(PPB-Visible-Width = 30) and a start position in the panel of 15
is specified, (PPB-First-Visible-Col = 15), Panels automatically
reduces the width of the window to 25 (PPB-Panel-Width is reduced
to 25).
The width or height of a window can be reduced to 0, in which case the
window disappears from the display. It does, however, retain its order
in the stack of panels on the screen (unlike the results of making a call
to PF-Disable-Panel).
The demonstration programpanelex1shows how this feature can be put to
good use. When any of the demonstration panels are moved, the program
does this using PF-Shift-Panel, with the height and width of the window
set to the same height and width as the panel.
A panel is moved to the right by increasing the value in
PPB-Panel-Start-Column. As the right-hand edge of the screen is reached,
Panels starts to clip the width so that the panel appears to disappear
off the right-hand edge of the screen.
A panel is moved to the left by decreasing the value in
PPB-Panel-Start-Column. When this reaches 0, the left-hand edge of the
screen has been reached. To give the impression of the panel
disappearing off the left-hand edge of the screen, the value of
PPB-First-Visible-Col is increased. The width of the window is reduced
by Panels as a result and the panel appears to slide off the edge of the
screen.
By always setting the PPB-Visible-Width to the maximum size before the
call to PF-Shift-Panel, panelex1 is letting Panels do the calculating of
exactly how much of the window can actually be displayed.
Panels Functions
The functions you can execute when using Panels are described in this
section in the order in which they appear in panlink.cpy. The
description of each function contains, where appropriate:
* The value of the function in panlink.cpy.
* The parameters you need to specify before making the call.
* The parameters Panels sets on return from the call.
* An example of the code required to make a call.
* Cross references to any related function.
PF-Get-Screen-Info (Value 0)
Returns information about the size of the current screen.
Parameters:
PPB-Panel-Height pic 9(4) comp.
PPB-Visible-Height pic 9(4) comp.
PPB-Panel-Width pic 9(4) comp.
PPB-Panel-Start-Row pic 9(4) comp.
PPB-Panel-Start-Column pic 9(4) comp.
PPB-First-Visible-Row pic 9(4) comp.
PPB-First-Visible-Col pic 9(4) comp.
PPB-Fill-Character pic 9(4) comp.
PPB-Fill-Attribute pic 9(4) comp.
On Entry:
None
On Exit:
PPB-Panel-Height The number of rows on the screen.
PPB-Visible-Height The number of rows on the screen.
PPB-Panel-Width The number of columns on the screen.
PPB-Visible-Width The number of columns on screen.
PPB-Panel-Start-Row 0
PPB-Panel-Start-Column 0
PPB-First-Visible-Row 0
PPB-First-Visible-Col 0
PPB-Fill-Character The current backdrop character.
PPB-Fill-Attribute The current backdrop attribute.
Example:
move pf-get-screen-info to ppb-function
call "PANELS" using panels-parameter-block.
if ppb-status not = zero
* (code to abort)
Remarks:
You can change the backdrop character and attribute using
PF-Set-Screen-Backdrop.
See also:
PF-Set-Screen-Backdrop
PF-Set-Screen-Backdrop (Value 1)
Changes the current backdrop character and attribute.
Parameters:
PPB-Fill-Character pic x. PPB-Fill-Attribute pic
x.
On Entry:
PPB-Fill-Character The new backdrop character to use.
PPB-Fill-Attribute The new backdrop attribute to use.
On Exit:
None
Example:
This example makes the backdrop character an asterisk. The backdrop
attribute is set to a red foreground on a blue background.
move "*" to ppb-fill-character
move X"14" to ppb-fill-attribute
move pf-set-screen-backdrop to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
* (code to abort)
Remarks:
This function does not automatically update the screen; it merely defines
the backdrop character and attribute to Panels. You must redraw the
screen using PF-Redraw-Screen before the the changed backdrop character
and attribute are displayed.
See Also:
PF-Redraw-Screen
PF-Redraw-Screen (Value 2)
Refreshes the contents of the entire screen.
Parameters:
None
Example:
move pf-redraw-screen to ppb-function.
call "PANELS" using panels-parameter-block
if ppb-status not = zero
* (code to abort)
Remarks:
Any panels currently visible on the screen are refreshed in the order in
which they previously appeared. Portions of the screen not hidden by
enabled panels display the current backdrop character and attribute.
On the first call to this function, the screen is cleared and the entire
screen is set to the current backdrop character and attribute.
This function is particularly useful if a screen becomes corrupted by
another program that uses a method of screen updating other than Panels.
This call resets the screen to a state recognized by Panels.
PF-Create-Panel (Value 3)
Creates a panel. The panel's window is created disabled; that is, it is
not visible.
Parameters:
PPB-Panel-Height pic 9(4) comp.
PPB-Panel-Height pic 9(4) comp.
PPB-Visible-Height pic 9(4) comp.
PPB-Visible-Width pic 9(4) comp.
PPB-Panel-Start-Column pic 9(4) comp.
PPB-Panel-Start-Row pic 9(4) comp.
PPB-First-Visible-Col pic 9(4) comp.
PPB-First-Visible-Row pic 9(4) comp.
PPB-Panel-ID pic 9(4) comp
On Entry:
PPB-Panel-Height The number of rows of text in the panel to be
created.
PPB-Panel-Width The number of columns of text in the panel to
be created.
PPB-Visible-Height The number of rows of text in the visible
window.
PPB-Visible-Width The number of columns of text in the visible
window.
PPB-Panel-Start-Column Positions the panel horizontally on the screen.
A value of 0 indicates that the left-hand edge
of the panel is positioned on the left-hand
edge of the screen.
PPB-Panel-Start-Row Positions the panel vertically on the screen.
A value of 0 indicates that the top of the
panel is positioned on the top edge of the
screen.
PPB-First-Visible-Col Positions the window horizontally within the
panel. A value of 0 indicates that the
left-hand edge of the window is positioned on
the left-hand edge of the panel.
PPB-First-Visible-Row Positions the window vertically within the
panel. A value of 0 indicates that the top of
the window is positioned on the top edge of the
panel.
On Exit:
PPB-Panel-ID The identifying handle of the created panel.
You should copy this value into a data item in
the Working-Storage Section of your program and
specify it when using any functions that act on
this panel.
Example:
This example creates a panel that is 20 characters wide by 15 lines high.
This panel starts on line 4, column 1 of the screen. The window into
this panel starts on the first line and first column of the panel. This
window is 20 characters wide by 10 rows deep. The window and panel are
shown in Figure 24-2.
![[]](../../pic3k/M015153/FFN103c50.gif)
Figure 24-2: Creating a Panel
* Panel size is 20 characters wide by 15 lines
move 20 to ppb-panel-width
move 15 to ppb-panel-height
* The window starts on screen line 4, col 1. Remember that
* PPB-Panel-Start-Column and PPB-Panel-Start-Row specify a
* screen position, where 0,0 is the top left corner of the
* screen.
move 3 to ppb-panel-start-row
move 0 to ppb-panel-start-column
* The window into the panel is 20 char wide by 10 lines.
move 20 to ppb-visible-width
move 10 to ppb-visible-height
* The window starts on the first line and column of the panel.
* Remember that 0,0 is the top right corner of the panel.
move 0 to ppb-first-visible-row
move 0 to ppb-first-visible-col
* Create the panel. It is initially disabled (invisible).
move pf-create-panel to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
* (code to abort)
...
* Save the panel identifier.
move ppb-panel-id to ws-save-panel-id
Remarks:
Panels allocates an area of memory for the new panel based on its size.
The number of bytes of memory used by a panel is determined as follows:
2 * PPB-Panel-Height * PPB-Panel-Width
The size of the new Panel can be larger than the screen, but you must
observe the following:
1. PPB-Panel-Width must not be greater than 2000.
2. PPB-Panel-Height * PPB-Panel-Width must not be greater than 65535.
Failure to observe either of these limits results in Panels error code 6
being returned. See the section Panels Error Codes for a description of
all Panels error codes.
Once you create a panel, you can change any of its variables except its
width and height, using PF-Shift-Panel. The newly created panel is
filled with the current backdrop character and attribute.
See Also:
PF-Shift-Panel
PF-Shift-Panel (Value 4)
Moves a window and/or changes its size.
Paremeters:
PPB-Panel-ID pic 9(4) comp.
PPB-Visible-Height pic 9(4) comp.
PPB-Visible-Width pic 9(4) comp.
PPB-Panel-Start-Column pic 9(4) comp.
PPB-Panel-Start-Row pic 9(4) comp.
PPB-First-Visible-Col pic 9(4) comp.
PPB-First-Visible-Row pic 9(4) comp.
On Entry:
PPB-Panel-ID The identifying handle of the panel whose
appearance you want to change. This value is
returned from a call to PF-Create-Panel.
PPB-Visible-Height The new number of rows of text in the visible
window.
PPB-Visible-Width The new number of columns of text in the
visible window.
PPB-Panel-Start-Column The new horizontal position of the panel on the
screen. A value of 0 indicates that the top
edge of the panel is positioned on the
left-hand edge of the screen.
PPB-Panel-Start-Row The new vertical position of the panel on the
screen. A value of 0 indicates that the top
edge of the panel is positioned on the top edge
of the screen.
PPB-First-Visible-Col The new horizontal position of the window
within the panel. A value of 0 indicates that
the left-hand edge of the window is positioned
on the left-hand edge of the panel.
PPB-First-Visible-Row The new vertical position of the window within
the panel. A value of 0 indicates that the top
edge of the window is positioned on the top
edge of the panel.
On Exit:
None
Example:
This example assumes a panel has been defined that is 80 characters wide
and 20 rows deep. The panel starts on line 1, column 1 of the screen.
The window into the panel is currently 80 columns wide and 5 rows deep
and starts in the first position (top left hand corner) of the panel.
The handle of this panel was saved in the data item ws-save-panel-id
This example makes more of the panel visible by increasing the visible
portion of the window from 5 rows to 10 rows. All other parameters
remain the same.
* Window starts in screen line 1, column 1. Remember that when
* the location of the window on the screen is defined, it is
* relative to 0 (that is line 0, row 0 is the top left hand
* corner of the screen).
move 0 to ppb-panel-start-column
move 0 to ppb-panel-start-row
* The window into the panel is 20 columns wide by 10 rows deep.
move 20 to ppb-visible-width
move 10 to ppb-visible-height
* The window starts at line 1, col 1 of the screen (where 0,0
* is the top left-hand corner of the screen).
move 0 to ppb-first-visible-col
move 0 to ppb-first-visible-row
* When the panel was first created, the returned panel ID was
* saved in a Working-Storage variable ws-save-panel-id. Now
* Panels needs to know which panel the call applies to.
move ws-save-panel-id to ppb-panel-id
* Move the window.
move pf-shift-panel to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
* (code to abort)
Remarks:
All of the fields except PPB-Panel-Height and PPB-Panel-Width can be
changed using this function - once you have defined the size of a panel
it cannot be changed. If you specify any values for PPB-Panel-Height and
PPB-Panel-Width they are ignored.
If you do not want to change the values already assigned to the window,
you can use Pf-Get-Panel-Info to learn the current size and position of
the window and set these again.
Any changes you make to the size or position of a window are visible only
if you have enabled the panel associated with the window. However, you
can change the window while the panel is disabled. The changes are
displayed the next time you use PF-Enable-Panel to enable the panel.
See Also:
PF-Create-Window, PF-Enable-Panel PF-Get-Panel-Info
PF-Get-Panel-Info (Value 5)
Finds out the size and position of an existing panel.
Parameters:
PPB-Panel-ID pic 9(4) comp.
PPB-Panel-Height pic 9(4) comp.
PPB-Panel-Width pic 9(4) comp.
PPB-Visible-Height pic 9(4) comp.
PPB-Visible-Width pic 9(4) comp.
PPB-Panel-Start-Column pic 9(4) comp.
PPB-Panel-Start-Row pic 9(4) comp.
PPB-First-Visible-Col pic 9(4) comp.
PPB-First-Visible-Row pic 9(4) comp.
On Entry:
PPB-Panel-ID The handle of the panel whose information you
want returned. This value is returned from a
call to PF-Create-Panel.
On Exit:
PPB-Panel-Height The height of the specified panel.
PPB-Panel-Width The width of the specified panel.
PPB-Visible-Height The height of the visible window in the
specified panel.
PPB-Visible-Width The width of the visible window in the
specified panel.
PPB-Panel-Start-Column The horizontal position of the specified panel
on the screen.
PPB-Panel-Start-Row The vertical position of the specified panel on
the screen.
PPB-First-Visible-Col The horizontal position of the visible window
on the specified panel.
PPB-First-Visible-Row The vertical position of the visible window on
the specified panel.
Example
This example returns information about the panel whose panel identifier
is saved in the variable ws-save-panel-id.
move ws-save-panel-id to ppb-panel-id
move pf-get-panel-info to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
* (code to abort)
PF-Delete-Panel (Value 6)
Deletes a panel from the system.
Parameters:
PPB-Panel-ID pic 9(4) comp.
On Entry:
PPB-Panel-ID The handle of the panel to be deleted.
On Exit:
None
Example:
This example deletes the panel whose identifier has been saved in the
variable ws-save-panel-id.
move ws-save-panel-id to ppb-panel-id
move pf-delete-panel to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
* (code to abort)
Remarks:
When you delete a panel, both the panel identifier and the storage area
that had been allocated to the panel becomes available for reuse. Any
attempt to access the panel after it has been deleted returns a Panels
error code 1, indicating that the attempt was unsuccessful. See the
section Panels Error Codes for a list of Panels error codes and their
meanings.
If you delete a panel that was enabled, it disappears from the screen.
PF-Enable-Panel (Value 7)
Enables a panel, making it visible on the screen.
Parameters:
PPB-Panel-ID pic 9(4) comp.
On Entry:
PPB-Panel-ID The identifying handle of the panel to enable.
On Exit:
None
Example:
This example enables the panel whose identifier is saved in data item
ws-save-panel-id.
move ws-save-panel-id to ppb-panel-id
move pf-enable-panel to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
* (code to abort)
Remarks:
You can create, move, change, or write to a panel before enabling it.
However, you must enable the panel before you can see the results of
these operations.
When you enable a panel, you are actually displaying the window
associated with that panel. The window appears in the position defined
when you created the panel, unless you recently changed or moved it.
If the enabled panel shares the same screen area as a visible panel that
was previously created, the newly enabled panel overlays the previously
created one.
If you have multiple panels in the program, they are stacked in the order
in which you enabled them. The most recently enabled panel overlays all
others on the screen.
You can move, change, read from and write to a panel even if it is
partially or fully overlaid by another.
See Also:
PF-Create-Panel
PF-Disable-Panel (Value 8)
Disables a panel, making it invisible.
Parameters:
PPB-Panel-ID pic 9(4) comp.
On Entry:
PPB-Panel-ID The identifying handle of the panel to disable.
On Exit:
None
Example:
This example disables the panel whose identifier is saved in variable
ws-save-panel-id.
move ws-save-panel-id to ppb-panel-id
move pf-disable-panel to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
* (code to abort)
Remarks:
Any windows that were overlaid by the disabled panel are now uncovered.
You can still work with the panel you disable, even though it is no
longer visible on the screen. To see the results of changes you make to
a disabled panel, you simply reenable it.
See Also:
PF-Create-Panel, PF-Enable-Panel