HP 3000 Manuals HP 3000 Manuals
Operation
This section gives you general information about using Panels.
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-block is a group item containing all the
fields you define when you are working
with Panels. A COPY-file that contains
all definitions for this group item is
provided in the file PANLINK.CPY
that comes with your software.
text-buffer is defined in your Working-Storage
Section. It contains text to be
included in a panel.
attribute-buffer is defined in your Working-Storage
Section.
It contains attributes to be included in
a panel.
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.
You define the text and attributes in the Working- Storage Section of
your program.
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 parameter
as the second parameter in the call. The dummy parameter can be any
variable. The syntax is as follows:
call "PANELS" using panels-parameter-block
dummy attribute-buffer
Text and Attributes for the Panel
You can specify text characters for the panel in two ways:
*
Define text-buffer in your Working-Storage Section and call Panels
using text-buffer as a parameter. This is used to fill an area
with different characters.
* Specify a value for PPB-Fill-Character in the parameter block.
This is used to fill an area with the same character.
You can specify attributes for the panel in two ways:
* Define attribute-buffer in your Working-Storage Section and call
Panels using attribute-buffer as a parameter. This is 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 attributes.
Panels Parameter Block
The Panels parameter block (shown below) is made up of fields that you
initialize to execute a particular function within Panels. Make sure
that you define all fields relevant to a function before calling Panels.
Each field is described later in this section. For your convenience, the
parameter block is in the file PANLINK.CPY provided with the Panels
software, and you can use the COPY verb to include it in your program.
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-Height PIC 9(4) COMP.
03 PPB-First-Visible-Col 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-Offset PIC 9(4) COMP.
03 PPB-Vertical-Stride PIC 9(4) COMP.
03 PPB-Update-Group.
05 PPB-Update-Count 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.
PPB-Function
The number of the function you want to perform must be specified for
every call to Panels. You enter the value of the function in this field.
Each function is described in detail later in this chapter. The
following list gives the function numbers and a brief description of each
function.
Function Number Description
0 Get screen information
1 Set screen backdrop
2 Redraw screen
3 Create panel
4 Move and Re-Size Window
5 Get panel information
6 Delete panel
7 Enable panel
8 Disable panel
9 Flush part of panel
10 Scroll part of panel
11 Write to part of panel
12 Read from part of panel
13 Find ID of panel at specified position
PPB-Status
Panels returns a status value to this field every time it is called. The
function was successfully executed if the PPB-Status field contains zero.
If Panels returns a value greater than zero, an error occurred while
Panels was trying to execute the function. A full list of status values
is given at the end of this chapter.
It is advisable to test the status field after every call to Panels.
PPB-Panel-Id
When you create a panel, Panels returns a panel identifier to this field.
Each panel you create will be given a unique panel identifier. You must
specify the panel identifier in this field when you are working with
Functions 4 through 12. Failure to specify the correct panel identifier
is a common cause of problems when using Panels.
Do not assume that Panels will allocate any particular identifier to a
particular panel. Neither should you assume that the same identifier
will be 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 in characters
of the panel in this field. 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 in characters of
the panel in this field. The height multiplied by the width of the panel
cannot exceed 65535 characters. If it does, Panels will return error
code 6 to the PPB-Status field.
Once you have created a panel, you cannot adjust its height.
PPB-Visible-Width
You define the width (in columns) of the visible window in the PPB-
Visible-Width field. This sets the number of columns that will initially
be visible on the screen when you enable the panel. The width of the
window cannot be wider than either the width of the panel or the screen.
PPB-Visible-Height
You define the height (in rows) of the visible window in this field.
This sets the number of rows that will initially be 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 this field determines the position of the
window relative to the left edge of the panel. If you set this field 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 this field determines the position of the
window relative to the top of the panel. If you set this field to 0, the
top of the window is aligned with the top of the panel.
PPB-Panel-Start-Column
The value you set for this field determines the left edge of the visible
window on the screen. If you set this field to 0, the visible window is
aligned with the first column on the screen.
PPB-Panel-Start-Row
The value you set for this field determines the top of the visible window
on the screen. If you set this field to 0, the visible window is aligned
with the first row on the screen.
PPB-Buffer-Offset
The value you specify in this field indicates 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 1 indicates the first byte in
the buffer.
PPB-Vertical-Stride
The value assigned to this field specifies 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 itself will assume that
enough data has been supplied, and this may lead to unpredictable
results.
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.
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.
Example
This panel is 20 characters wide by 25 rows deep. This example updates
the shaded portion of the panel (see Figure 25-1 ).
![[]](../../pic3k/M013032/FFN243c50.gif)
Figure 25-1. Updating Part of the Panel
* Update 406 characters of the panel (6 characters on the fifth line
plus 20 full lines, each line 20 characters wide) by moving 406 to
PPB-Update-Count.
* Tell Panels where within the rectangle to start updating. Since
updating starts on the fifth line of the rectangle, beginning with
the fifteenth character, 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-Rectangle-Offset
This field specifies how many characters not to update within the
rectangle. The value you define to this field 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, 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.
See PPB-Update-Count for an example.
PPB-Update-Start-Col
This field defines the position of the rectangle within the panel. It
defines the first column of the rectangle that will be affected when you
update the panel. If you specify 0 in this field, the first column to be
updated is the leftmost column of the panel.
PPB-Update-Start-Row
This field defines the position of the rectangle within the panel. It
defines the first row of the rectangle that will be affected when you
update the panel. If you specify 0 in this field, the first row to be
updated is the top row of the panel.
PPB-Update-Width
This field defines the size in characters of the rectangle to update.
The number defined in this field is the number of columns that will be
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 of the rectangle to update. You specify a
value in this field to determine the number of rows that will be 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 this field to define either the backdrop character for the screen
or a single character to fill a designated area of a panel. The initial
value for this field is SPACE.
PPB-Fill-Attribute
You use this field 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".
PPB-Update-Mask
You use the 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 Functions 9 (Flush Part of Panel), 10 (Scroll
Part of Panel), 11 (Write to Part of Panel), and 12 (Read from Part of
Panel) as shown below.
Bit Meaning
7 Unused. Reserved for future use and should be set
to zero.
6 Unused. Reserved for future use and should be set
to zero.
5
Any update to the attributes in the panel is to
show on the screen immediately (provided the panel
is enabled). If this bit is not set, the update
will not show on the screen till the next Flush
Part of Panel is done.
4 Any update to the text in the panel is to show on
the screen immediately (provided the panel is
enabled). If this bit is not set, the update will
not show on the screen till the next Flush Part of
Panel is done.
3 The attributes in the specified area of the panel
are to be replaced by the attribute specified in
the PPB-Fill-Attribute field in the parameter
block.
2 The text in the specified area of the panel is to
be replaced by the character specified in the
PPB-Fill-Character field in the parameter block.
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.
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.
Notes:
* Bits 0 and 2 are mutually exclusive, as are bits 1 and 3. If you
set either pair, the results are unpredictable.
* Bits are ordered with bit 7 as the most significant, or first, and
bit 0 as the least significant, or last.
* Function 12 (Read Panel) uses only bits 0 and 1.
PPB-Scroll-Direction
You use this field 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 define in this field the number of rows or columns you wish to
scroll. If you are scrolling up or down, the value in this field
determines the number of rows to be scrolled. If you scroll to the left
or right, the specified number of columns will be scrolled.
Clipping Window Height and Width
When a panel is created or the window is moved or resized using the Shift
panel function, 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 only
describes 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):
* 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 will be
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
will be clipped by 20 characters (that is, PPB-Visible-Width will
be truncated to 20).
* 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 will be reduced so that it is completely in the panel.
For example, if a panel has been created with a width (PPB-Panel-
Width) of 40 and a window width (PPB-Visible-Width) of 30 and a
start position in the panel (PPB-First-Visible-Col) of 15 is
specified, Panels will automatically reduce the width of the
window to 25.
The width or height of the window can be reduced to 0, in which
case the window will have disappeared from the display. It will,
however, retain its order in the stack of panels on the screen
(unlike the results of the Disable function).
The demonstration program
panelex1
shows how this feature can be put to good use. When any of the
demonstration panels are moved, the program does this using the Shift
function, 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
will start 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 will be reduced by Panels as a result
and the panel will appear to slide off the edge of the screen.
By always setting the value of PPB-Visible-Width to the maximum size
before the call to do the Shift, panelex1 is letting Panels do the
calculating of exactly how much of the window can actually be displayed.