HP 3000 Manuals HP 3000 Manuals
Panels Functions
The functions you can execute when using Panels are described in this
section in order of function number. The description of each function
begins with a list of fields that you must set when using the function.
Fields that a particular function does not use are ignored by the
function.
Function 0 - Get Screen Information
Required fields:
PPB-Function.
You use this function to return the size of the screen. When you set
PPB-Function to 0, the following parameter block fields are set to the
values shown below:
Field Value
PPB-Panel-Height Number of rows on screen
PPB-Visible-Height Number of rows on screen
PPB-Panel-Width Number of columns on screen
PPB-Visible-Width 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 Current backdrop character
PPB-Fill-Attribute Current backdrop attribute
The current backdrop character is the character displayed on any area of
the screen not covered by an enabled panel. The initial value of the
backdrop character field is SPACE.
The current backdrop attribute is the attribute displayed by the backdrop
character. The initial value for the attribute field is the backdrop
attribute normally associated with your machine. The normal attribute is
x"07" (that is, white text on a black background).
You can change the backdrop character and attribute with function 1.
Example
move zero to ppb-function
call "PANELS" using panels-parameter-block.
if ppb-status not = zero
(code to abort)
Function 1 - Set Backdrop Character and Attribute
Required Fields:
PPB-Function
PPB-Fill-Character
PPB-Fill-Attribute
You change the current backdrop character and attribute by specifying the
character and attribute values in the PPB-Fill-Character and PPB- Fill-
Attribute fields, respectively. You then set PPB-Function to 1 and call
Panels.
This function does not automatically update the screen; it merely defines
the backdrop character and attribute to Panels. You must redraw the
screen (Function 2) before the system displays the changed backdrop
character and attribute.
Example
This example makes the backdrop character an asterisk.
move "*" to ppb-fill-character
move 1 to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
(code to abort)
Function 2 - Redraw Entire Screen
Required fields:
PPB-Function
You use this function to refresh the contents of the entire screen. 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 will reset the screen to a state recognized by Panels.
Example
move 2 to ppb-function.
call "PANELS" using panels-parameter-block
if ppb-status not = zero
(code to abort)
Function 3 - Create a Panel
Required fields:
PPB-Function
PPB-Panel-Height
PPB-Panel-Width
PPB-Visible-Height
PPB-Visible-Width
PPB-Panel-Start-Column
PPB-Panel-Start-Row
PPB-First-Visible-Col
PPB-First-Visible-Row
Returned fields:
PPB-Panel-ID
Note: The panel's window is created disabled - it is not visible.
You must specify the following information before you can call Panels to
create a panel.
* Height and width of the panel
* Height and width of the window
* Position of the window within the panel
* Position of the window on the screen
(See below for details of how to initialize these fields.)
All column and row numbers on the screen and within a panel begin with 0.
Once you create a panel, you can change any of its variables except its
panels width and height. (See Function 4 later in this chapter). The
newly created panel is filled with the current backdrop character and
attribute.
Successful creation of a panel sets the PPB-Status field value to 0.
Panels also returns the identifier of the panel in the PPB-Panel-ID
field. Copy this identifier into your Working-Storage Section and use
this value for any function you will execute for this newly created
panel.
Height and Width of Panel
The height of the panel is the number of rows of text in the panel. You
define the number of rows in the PPB-Panel-Height field.
The width of the panel is the number of columns of text. You set the
PPB-Panel-Width field to this number.
Panels allocates an area of memory for the panel based on the specified
height and width. The number of bytes of memory used by the panel is
determined as follows:
2 * height of panel * width of panel
The size of the panel can be larger or smaller than the screen; however,
there is a maximum size that you cannot exceed.
* The width cannot exceed 2000 characters.
* The height multiplied by the width cannot exceed 65535.
If you exceed either of these limits, Panels returns error code 6 in the
status field (PPB-Status) and does not create the panel.
Height and Width of the Window Within the Panel
The height of the window is the number of rows of text in the window.
You define the number of rows in the PPB-Visible-Height field.
The width of the window is the number of columns of text. You set the
PPB-Visible-Width field to this number.
Positioning the Window Within the Panel
You position the window within the panel by setting the
PPB-First-Visible-Col and PPB-First-Visible-Row fields to the desired
column and row.
The number specified in the PPB-First-Visible-Col field defines the
position of the window relative to the left edge of the panel. The
number set in the PPB-First-Visible-Row field defines the position of the
window relative to the top edge of the panel. If you set both fields to
0, the top left corner of the panel is visible in the window.
Positioning the Window on the Screen
The position of the window is relative to its position on the screen.
You specify the left side of the window by entering the column number in
the PPB-Panel-Start-Column field. You define the top of the window
relative to the top of the screen by specifying the row number in the
field PPB-Panel-Start-Row. When both of these fields are set to 0, the
window is positioned at the top left corner of the screen.
Example
This example creates a panel that is 20 characters wide by 15 lines high.
This panel starts on screen line 4, column 1. The window into this panel
starts on the first line and first column of the panel. This window will
be 20 characters wide by 10 rows deep (see Figure 25-2 ).
![[]](../../pic3k/M013032/FFN253c50.gif)
Figure 25-2. Positioning a Window
* Panel size is 20 characters wide by 15 lines
move 20 to ppb-panel-width
move 15 to ppb-panel-height
* Window will start 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 will initially be disabled (invisible).
move 3 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
Function 4 - Move and Re-Size Window
Required fields:
PPB-Function
PPB-Visible-Height
PPB-Visible-Width
PPB-Panel-Start-Column
PPB-Panel-Start-Row
PPB-First-Visible-Col
PPB-First-Visible-Row
PPB-Panel-ID
This function lets you move a window as well as change its size. As you
can see from the list above, all of the fields except for PPB-Panel-
Height and PPB-Panel-Width can be altered using this function. Remember
that once you have defined the size of a panel, it cannot be changed.
Panels ignores any values defined to PPB-Panel-Height or PPB-Panel-Width.
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 will be
displayed the next time you enable the panel.
If you do not want to change the values already assigned to the window,
you can use Function 5 (Get Panel Information) to learn the current size
and position of the window and set these again.
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.
This example will make 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, col 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 on the panel is 20 cols 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 will apply to.
move ws-save-panel-id to ppb-panel-id
* Move the window.
move 4 to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
(code to abort)
Function 5 - Get Panel Information
Required fields:
PPB-Function
PPB-Panel-ID
You can find out the size and position of an existing panel by using
Function 5. Values for the following fields are automatically returned
by Panels:
PPB-Panel-Height
PPB-Panel-Width
PPB-Visible-Height
PPB-Visible-Width
PPB-Panel-Start-Column
PPB-Panel-Start-Row
PPB-First-Visible-Col
PPB-First-Visible-Row
Example
This example gets 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 5 to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
(code to abort)
Function 6 - Delete a Panel
Required fields:
PPB-Function
PPB-Panel-ID
To delete a panel from the system, you simply move the panel identifier
to PPB-Panel-ID and set PPB-Function to 6. If the panel was enabled, it
disappears from the screen.
When you delete a panel, both the panel identifier and the storage area
that had been allocated to the panel becomes available for re-use. Any
attempt to access the panel after it has been deleted returns a value of
1 in the PPB-Status field, indicating that the attempt was unsuccessful.
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 6 to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
(code to abort)
Function 7 - Enable a Panel
Required fields:
PPB-Function
PPB-Panel-ID
You enable a panel to make it visible on the screen by using Function 7.
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 will overlay 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.
Example
This example enables (makes visible) the panel whose identifier is saved
in variable ws-save-panel-id.
move ws-save-panel-id to ppb-panel-id
move 7 to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
(code to abort)
Function 8 - Disable a Panel
Required fields:
PPB-Function
PPB-Panel-ID
You disable a panel to make it invisible. You identify the panel to be
disabled by moving its identifier to PPB-Panel-ID.
Any windows that were overlaid by the disabled panel are now uncovered.
You can still work with this panel even though it is no longer visible on
the screen. To see the results of changes you make to a disabled panel,
you simply re-enable it.
Example
This example disables (makes invisible) the panel whose identifier is
saved in variable ws-save-panel-id.
move ws-save-panel-id to ppb-panel-id
move 8 to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
(code to abort)
Function 9 - Flush Part of Panel
Required fields:
PPB-Function
PPB-Panel-ID
PPB-Update-Height
PPB-Update-Width
PPB-Update-Start-Row
PPB-Update-Start-Col
PPB-Rectangle-Offset
PPB-Update-Count
PPB-Update-Mask
This function updates the screen with changes to the panel that have not
yet been applied because bit 4 or 5 in the update mask was off. If the
panel is not enabled this function has no effect.
You must set bits 4 and 5 of the update mask before calling this
function. This is to select whether updates to attributes, text or both
are to be applied.
Whenever you make a change to a panel you are updating it. Here you are
copying updated information to the screen. Thus, most of the required
fields for this function have to do with updating.
Example
This example assumes a panel has been defined that is 30 characters wide
and 17 rows deep. This example updates the screen display of part of the
panel starting with the second line of the panel, at column 1, through
the 16th line of the panel (see Figure 25-3 ).
![[]](../../pic3k/M013032/FFN263c50.gif)
Figure 25-3. Flush Part of a Panel
* Define the size of the rectangle to flush
move 30 to ppb-update-width
move 15 to ppb-update-height
* Within the defined rectangle, apply updates beginning with the
* first character (relative to 0).
move 0 to ppb-rectangle-offset
* Now define where in the panel the rectangle starts (0,0)
* defines the top left-hand corner of the panel). The update
* panel starts on line 2, col 1 of the panel.
move 1 to ppb-update-start-row
move 0 to ppb-update-start-col
* The update rectangle contains 450 characters (15 lines times 30
* characters per line).
move 450 to ppb-update-count
* Set bits 4 and 5 of the Update Mask on to apply updates for
* both text and attributes. Hex 30 is binary 00110000.
move X"30" to ppb-update-mask
* When the panel was created, it was saved with the panel
* identifier in a variable ws-save-panel-id.
move ws-save-panel-id to ppb-panel-id
*Apply the updates
move 9 to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
(code to abort)
Function 10 - Scroll a Rectangle in a Panel
Required fields:
PPB-Function
PPB-Update-Height
PPB-Update-Width
PPB-Update-Start-Row
PPB-Update-Start-Col
PPB-Scroll-Direction
PPB-Scroll-Count
PPB-Update-Mask
PPB-Panel-ID
If you set bit 0 of the PPB-Update-Mask, then you must include a
text-buffer, PPB-Buffer-Offset and PPB-Vertical- Stride in your call to
Panels.
If you set bit 1 of the PPB-Update-Mask, then you must include an
attribute-buffer, PPB-Buffer-Offset and PPB-Vertical-Stride in your call
to Panels.
If you set bit 2 of the PPB-Update-Mask, you must include PPB-Fill-
Character.
If you set bit 3 of the PPB-Update-Mask, you must include PPB-Fill-
Attribute.
A rectangle is a specific area within a panel. You can scroll this
identified area either up or down by row, or left or right by column.
Panels does not allow you to scroll text and attributes separately.
You must supply the following information:
* Size of rectangle to be scrolled.
* Position within the panel of rectangle to be scrolled.
* Direction in which rectangle is to be scrolled.
* Number of rows or columns to be scrolled.
* Data to replace area vacated by data that was scrolled.
Example
A panel has been defined that is 50 characters wide and 15 rows deep.
This example scrolls the text and attributes in the panel up 15 rows and
replaces the vacated text with text and attributes from text and
attribute buffers (see Figure 25-4 ). The first 15 lines of the text
and attribute buffers are already used (displayed on the screen).
Therefore, scrolling starts with the 16th line of the text and attribute
buffer (one row in the text and attribute buffers is 50 characters wide).
![[]](../../pic3k/M013032/FFN273c50.gif)
Figure 25-4. Scrolling Part of a Panel
* Define an "update rectangle"
* (that is, a block of the panel toscroll).
* In this case, define the entire panel as the rectangle.
move 50 to ppb-update-width
move 15 to ppb-update-height
* Since the update rectangle is the same size as the panel,
* begin scrolling with line 1, col 1 of the panel
* (where 0,0 is the top left-hand corner of the panel).
move 0 to ppb-update-start-row
move 0 to ppb-update-start-col
* The rectangle will scroll up.
move 0 to ppb-scroll-direction
* Scroll up 15 lines.
move 15 to ppb-scroll-count
* The panel will be filled with text and attributes from user
* specified buffers. The first 15 lines (each line in the buffer
* is 50 characters wide) are already displayed. Start updating
* with the16th line of the buffers. PPB-Buffer-Offsetspecifies
* what character of the buffers to begin with (where 1 is the
* firstcharacter). Therefore, start with the 751st character
* (15 rows times 50 characters per row equals 750 characters
* already on the screen).
move 751 to ppb-buffer-offset
* One row of the "update rectangle" is 50 characters wide.
move 50 to ppb-vertical-stride
* Update the vacated portions of the panel using text and
* attribute buffers (set bits 0 and 1 of PPB-Update-Mask) and
* changes will be seen on the screen as the rectangle scrolls in
* the enabled panel(set bits 4 and 5 of PPB-Update-Mask).
* Hex 33 is binary 00110011.
move x"33" to ppb-update-mask
* The panel ID was saved in ws-save-panel-id.
move ws-save-panel-id to ppb-panel-id
* Scroll the panel. The text buffer is ws-text-buffer and the
* attribute buffer is ws-attribute-buffer.
move 10 to ppb-function
call "PANELS" using panels-parameter-block
ws-text-buffer
ws-attribute-buffer
if ppb-status not = zero
(code to abort)
Function 11 - Write to Part of a Panel
Required fields:
PPB-Function
PPB-Panel-ID
PPB-Update-Height
PPB-Update-Width
PPB-Update-Start-Row
PPB-Update-Start-Col
PPB-Buffer-Offset
PPB-Vertical-Stride
PPB-Rectangle-Offset
PPB-Update-Count
PPB-Update-Mask
If you set bit 0 of the PPB-Update-Mask, then you must include a text-
buffer, PPB-Buffer-Offset and PPB- Vertical-Stride in your call to
Panels.
If you set bit 1 of the PPB-Update-Mask, then you must include an
attribute-buffer, PPB-Buffer-Offset and PPB-Vertical-Stride in your call
to Panels.
If you set bit 2 of the PPB-Update-Mask, you must include PPB-Fill-
Character. If you set bit 3 of the PPB-Update-Mask, you must include
PPB-Fill- Attribute.
When you are writing to a panel, you are actually updating it at the same
time. Therefore, many of the fields you define have to do with updating.
Text and attributes you write to the panel are visible on the screen if
you use bits 4 and 5 in the PPB-Update-Mask field, and the panel is
enabled.
Example
This example assumes a panel has been defined that is 50 characters wide
and 15 rows deep. This example writes the first 15 rows from the text
and attribute buffers to the panel (see Figure 25-5 ).
![[]](../../pic3k/M013032/FFN283c50.gif)
Figure 25-5. Write to Part of a Panel
* Define an update rectangle (that is a block of the panel to
* update). In this case, define the entire panel as the
* rectangle.
move 50 to ppb-update-width
move 15 to ppb-update-height
* Since the "update rectangle" is the same size as the panel, the
* update window has no offset within the panel.
move 0 to ppb-update-start-row
move 0 to ppb-update-start col
* Write using text and attribute buffers starting with the first
* character of the buffers.
move 1 to ppb-buffer-offset
* One row of the update window is 50 characters wide.
move 50 to ppb-vertical-stride
* Start writing beginning with the firstcharacter of the update
* window (where 0 is the top left-hand corner of the window).
move 0 to ppb-rectangle-offset
* Write 750 characters (15 rows times 50 characters per row) to
* the panel.
move 750 to ppb-update-count
* Use text and attribute buffers (set bits 0 and 1 of
* PPB-Update-Mask) and have the text immediately visible on the
* screen if the panel is enabled (set bits 4 and 5 of
* PPB-Update-Mask). Hex 33 is binary 00110011.
move X"33" to ppb-update-mask
* The panel identifier was saved in "ws-save-panel-id".
move ws-save-panel-id to ppb-panel-id
* Write to the panel. The text buffer is ws-text-buffer and the
* attribute buffer is ws-attribute-buffer.
move 11 to ppb-function
call "PANELS" using panels-parameter-block
ws-text-buffer
ws-attribute-buffer
if ppb-status not = zero
(code to abort)
Function 12 - Read From Part of a Panel
Required fields:
PPB-Function
PPB-Panel-ID
PPB-Update-Height
PPB-Update-Width
PPB-Update-Start-Row
PPB-Update-Start-Col
PPB-Rectangle-Offset
PPB-Update-Count
PPB-Buffer-Offset
PPB-Vertical-Stride
PPB-Update-Mask*
If you set bit 0 of the PPB-Update-Mask, then you must include a text-
buffer to hold the text information read back.
If you set bit 1 of the PPB-Update-Mask, then you must include an
attribute-buffer to hold the attribute information read back.
You read text and attributes from a panel into buffers supplied by the
calling program. Reading from a panel is considered an update process,
so many of the fields have to do with updating. You set the
PPB-Buffer-Offset and PPB-Vertical-Stride fields to indicate those parts
of the buffers to be updated.
Notes:
* This function does not behave like an ACCEPT (that is, it will not
allow the user to input information to a panel). If you want to
obtain information from the user, you must issue an ACCEPT.
* You must make sure that the buffers are large enough to
accommodate
the data that Panels will place into them. If they are not large
enough, Panels may write data over those parts of your program
following the buffers.
* The Read function within Panels recognizes only two bit settings
for the PPB-Update-Mask field:
Bit 1 causes the attributes from a specific area
in the panel to be placed in a buffer. The
attribute buffer is always the third
parameter specified in the call to Panels.
Bit 0 causes the text from the specified area in
the panel to be placed in a buffer. The
text buffer is always the second parameter
specified in the call to Panels.
Bits 2 through 7 are not used by this function.
Example
This example assumes a panel has been defined that is 10 characters wide
and 30 rows deep. This example reads a portion of this panel, starting
with the 7th line,first column to the end of the panel. Read only text
(not attributes) into a buffer called WS-Text-Buffer starting at the
first character of the buffer (see Figure 25-6 ).
![[]](../../pic3k/M013032/FFN293c50.gif)
Figure 25-6. Read from Part of a Panel
* Define an "update rectangle" to read from. In this case,
* define the rectangle from line 7 through line 30 of the panel.
* This is a total of 24 lines and each line is 10 characters
* wide.
move 10 to ppb-update-width
move 24 to ppb-update-height
* Start reading beginning with the 7th line and first column of
* the panel. (0,0 is the top left-hand corner of the panel.)
move 6 to ppb-update-start-row
move 0 to ppb-update-start col
* Within the rectangle, read beginning with the first character
* (where 0 is the top left-hand corner of the rectangle).
move 0 to ppb-rectangle-offset
* Read 240 characters into the buffers (24 lines times 10
* characters per line).
move 240 to ppb-update-count
* Read will update beginning with the first character of
* the buffer.
move 1 to ppb-buffer-offset
* One row of the update rectangle is 10 characters wide.
move 10 to ppb-vertical-stride
* Read text only, not attributes (set bit 0 of PPB-Update-Mask).
move x"01" to ppb-update-mask
* The panel identifier was saved in ws-save-panel-id.
move ws-save-panel-id to ppb-panel-id
* Read text from the panel into "ws-text-buffer", defined
* as PIC X(240).
move 12 to ppb-function
call "PANELS" using panels-parameter-block
ws-text-buffer
if ppb-status not = zero
(code to abort)
Function 13 - Identify Panel at Position
Required fields:
PPB-Function
PPB-Panel-Start-Column
PPB-Panel-Start-Row
This function first determines if there is a panel at the position
specified in the PPB-Panel-Start-Column and PPB-Panel-Start-Row fields.
If a panel exists at that position, the function returns the panel
identifier to the PPB-Panel-ID field. It also sets all of the following
fields (also returned by Function 5-Get Panel Information):
PPB-Panel-ID
PPB-Panel-Height
PPB-Panel-Width
PPB-Visible-Height
PPB-Visible-Width
PPB-Panel-Start-Column
PPB-Panel-Start-Row
PPB-First-Visible-Col
PPB-First-Visible-Row
If more than one panel is located at the specified position, the function
returns the panel identifier of the panel most recently enabled. If
there is no enabled panel at the specified location, the function returns
a value of 0 to the PPB-Panel-ID field.
Example
This example identifies which panel is at line 4, column 6 (where 0,0 is
the top left-hand corner of the screen).
move 3 to ppb-panel-start-row
move 5 to ppb-panel-start-column
move 13 to ppb-function
call "PANELS" using panels-parameter-block
if ppb-status not = zero
(code to abort)