Using Screens

Using Panels

Chapter 11: Panels

Panels is a module that enables you to build windowing into an application. It comprises a set of routines that you can call from your COBOL programs. The windowing features provided include overlapping windows, separate or synchronized updating of text and attributes, scrolling of text across a window and the creation of popup/pulldown menus.

11.1 Overview

Panels enables you to create up to 65534 panels and to have 254 panels visible on the screen (subject to your machine having enough memory).

Panels takes care of maintaining the areas of the screen that are overlaid by another window automatically. It is intended for programmers who require high performance screen handling facilities. Examples of components in this COBOL system that themselves use Panels include the Advanced Animator (available in an add-on product) and Screens.

The basic concept provided by Panels is that of a panel. This can be considered as a virtual screen that can be written to just like a real screen. However, a panel can be larger or smaller than the real screen.

The contents of a panel are viewed through a window. It is the window associated with a panel that is actually displayed on the real screen. The window can be smaller than the actual size of the panel, in which case only part of the panel's contents are visible. The part of the panel which is visible through the window can be varied by the programmer. Up to 254 windows can be displayed on the screen at once, overlapping each other if necessary.

The window associated with a particular panel can either be visible on the screen (enabled) or it can be invisible (disabled). Even if the panel is disabled, it can still be written to, but its contents are not visible on the screen until the panel is enabled again. The position and size of a window on the screen can be altered at any time.

Any part of a panel can be written to or read from by a program. Also, any rectangular region of a panel can be scrolled in any direction.

11.1.1 Frequently Used Terms

Adis

The run-time module that executes extended ACCEPT/DISPLAY statements. The Adis module can be told to DISPLAY data in a panel rather than directly on the screen and to ACCEPT data from a panel.

Attribute Buffer

The attributes defined in the Working-Storage Section of your program which are then included in a panel.

Clipping

Reducing the window size if the specified size is larger than can be created. For example, 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 automatically reduced to fit the screen.

Disabled

A particular window is not visible on the screen.

Enabled

A particular window is visible on the screen.

Panel

A virtual screen that can be written to, but which can be larger or smaller than the real screen. Before a panel can be used, it must be created by supplying the height and width of the panel together with the dimensions and position of the visible portion on the screen and which part of the panel is actually visible.

Parameter Block

The means of communication between a program and Panels. The parameter block is made up of fields that you initialize to execute a particular function within Panels. All fields relevant to a function must be initialized before calling Panels.

Rectangle

A rectangular portion of a panel, which can be scrolled independently.

Text Buffer

Text defined in the Working-Storage Section of your program which is then included in a panel.

Window

The visible portion of a panel.

11.2 Operation

This section gives you general information about Panels.

11.2.1 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 the parameters are:

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 parameter as 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

11.2.2 Text and Attributes for a Panel

You can specify text characters for a panel in three 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.

• Using the ACCEPT and DISPLAY statements for formatted screen I/O within a panel.

You can specify attributes for a panel in three 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.

• Using the ACCEPT and DISPLAY statements for formatted screen I/O that specifies attributes or colors for a panel.

Panels associates one attribute-encoding byte with each text character. When a panel is displayed on the screen, each text character is displayed with attributes encoded in the corresponding attribute-encoding byte.

There are four types of encoding:

• Standard PC monochrome attribute encoding. This is the default encoding for Panels on DOS, Windows and OS/2 for systems with a monochrome display.

• Standard PC color attribute encoding. This is the default encoding for Panels on DOS, Windows and OS/2 for systems with a color display.

• Default UNIX monochrome attribute encoding. This is the default encoding for Panels on UNIX regardless of whether the terminfo description for the terminal specifies color or not.

• User selected or generic attribute encoding for all types of display. See the chapter Generic Display Attributes.

You can determine the type of encoding used by Panels by calling an RTS library routine. See your release notes for details. See the chapter Display Attributes for details on attribute encoding.

UNIX :
You may have a program that has been developed to use Panels on DOS, Windows or OS/2, that you wish to run on UNIX. You can do this if you make a call to CBL_SCR_SET_PC_ATTRIBUTES (it takes no parameters) before the first ACCEPT or DISPLAY statement or call to Panels is executed. The CBL_SCR_SET_PC_ATTRIBUTES routine sets the attribute and color palette to use PC mono or color encoding, as appropriate for the terminfo entry for the terminal. For details on the routine see the chapter Low-level Routines for Character Interfaces.

ACCEPT and DISPLAY statements use Adis to support terminal I/O and when used with Panels, Adis and Panels must use the same attribute encoding. This is automatically provided.

11.2.3 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 copyfile 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-x. 
    03 PPB-Status                   pic 9(2) comp-x. 
    03 PPB-Panel-ID                 pic 9(4) comp-x. 
    03 PPB-Panel-Width              pic 9(4) comp-x. 
    03 PPB-Panel-Height             pic 9(4) comp-x. 
    03 PPB-Visible-Width            pic 9(4) comp-x. 
    03 PPB-Visible-Height           pic 9(4) comp-x. 
    03 PPB-First-Visible-Col        pic 9(4) comp-x. 
    03 PPB-First-Visible-Row        pic 9(4) comp-x. 
    03 PPB-Panel-Start-Column       pic 9(4) comp-x. 
    03 PPB-Panel-Start-Row          pic 9(4) comp-x. 
    03 PPB-Buffer-Offset            pic 9(4) comp-x. 
    03 PPB-Vertical-Stride          pic 9(4) comp-x. 
    03 PPB-Update-Group. 
       05 PPB-Update-Count          pic 9(4) comp-x. 
       05 PPB-Rectangle-Offset      pic 9(4) comp-x. 
       05 PPB-Update-Start-Col      pic 9(4) comp-x. 
       05 PPB-Update-Start-Row      pic 9(4) comp-x. 
       05 PPB-Update-Width          pic 9(4) comp-x. 
       05 PPB-Update-Height         pic 9(4) comp-x. 
    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-x. 
    03 PPB-Scroll-Count             pic 9(4) comp-x.

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.

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.

We recommend you 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-Height. 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 resulting 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 11-1 shows a panel 20 characters wide by 25 rows deep.

Figure 11-1: Updating Part of a Rectangle

If you want to update the unshaded part of the panel you have to use PPB-Update-Count and PPB-Rectangle-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.

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 characters, 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 a designated area of a panel. The default backdrop character is space if you do not explicitly define it.

PPB-Fill-Attribute

You use the PPB-Fill-Attribute to define the attribute of the backdrop character for the screen or the attribute you specify to fill a designated area of a panel. The default (initial) value for the backdrop attribute 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:

Notes:

• 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:

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.

11.2.4 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. 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 sample program panelex1.cbl shows 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.cbl is letting Panels do the calculating of exactly how much of the window can actually be displayed.

11.2.5 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-x.
PPB-Visible-Height              pic 9(4) comp-x.
PPB-Panel-Width                 pic 9(4) comp-x.
PPB-Panel-Start-Row             pic 9(4) comp-x.
PPB-Panel-Start-Column          pic 9(4) comp-x.
PPB-First-Visible-Row           pic 9(4) comp-x.
PPB-First-Visible-Col           pic 9(4) comp-x.
PPB-Fill-Character              pic 9(4) comp-x.
PPB-Fill-Attribute              pic 9(4) comp-x.

On Entry:

None

On Exit:

Example:

     move pf-get-screen-info to ppb-function. 
     call "PANELS" using panels-parameter-block. 
     if ppb-status not = zero 
 *       (code to abort)

Comments:

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:

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)

Comments:

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 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)

Comments:

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-x.
PPB-Panel-Width                 pic 9(4) comp-x.
PPB-Visible-Height              pic 9(4) comp-x.
PPB-Visible-Width               pic 9(4) comp-x.
PPB-Panel-Start-Column          pic 9(4) comp-x.
PPB-Panel-Start-Row             pic 9(4) comp-x.
PPB-First-Visible-Col           pic 9(4) comp-x.
PPB-First-Visible-Row           pic 9(4) comp-x.
PPB-Panel-ID                    pic 9(4) comp.

On Entry:

On Exit:

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 11-2.

Figure 11-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 left 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.

Comments:

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:

• PPB-Panel-Width must not be greater than 2000.

• 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.

Parameters:

PPB-Panel-ID                    pic 9(4) comp-x.
PPB-Visible-Height              pic 9(4) comp-x.
PPB-Visible-Width               pic 9(4) comp-x.
PPB-Panel-Start-Column          pic 9(4) comp-x.
PPB-Panel-Start-Row             pic 9(4) comp-x.
PPB-First-Visible-Col           pic 9(4) comp-x.
PPB-First-Visible-Row           pic 9(4) comp-x.

On Entry:

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)

Comments:

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 and 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-x.
PPB-Panel-Height                pic 9(4) comp-x.
PPB-Panel-Width                 pic 9(4) comp-x.
PPB-Visible-Height              pic 9(4) comp-x.
PPB-Visible-Width               pic 9(4) comp-x.
PPB-Panel-Start-Column          pic 9(4) comp-x.
PPB-Panel-Start-Row             pic 9(4) comp-x.
PPB-First-Visible-Col           pic 9(4) comp-x.
PPB-First-Visible-Row           pic 9(4) comp-x.

On Entry:

On Exit:

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-x.

On Entry:

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)

Comments:

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-x.

On Entry:

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)

Comments:

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-x.

On Entry:

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)

Comments:

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 re-enable it.

See Also:

PF-Create-Panel, PF-Enable-Panel

PF-Flush-Panel (Value 9)

Updates the screen with changes to the specified panel that have not yet been applied because bit 4 or 5 in PPB-Update-Mask was off during previous calls to Panels. See the section The Panels Parameter Block for a description of PPB-Parameter-Block.

Parameters:

PPB-Panel-ID                    pic 9(4) comp-x.
PPB-Update-Height               pic 9(4) comp-x.
PPB-Update-Width                pic 9(4) comp-x.
PPB-Update-Start-Row            pic 9(4) comp-x.
PPB-Update-Start-Col            pic 9(4) comp-x.
PPB-Update-Mask                 pic x.

On Entry:

On Exit:

None

Example:

This example assumes a panel has been defined that is 30 characters wide and 17 rows deep. The screen display of the original panel is updated, starting with the second line, column 1, through the 16th line of the panel (see Figure 11-3). The handle of the original panel is assumed to be saved in data item ws-save-panel-id.

Figure 11-3: Updating Part of a Panel's Display

 * Define the size of the rectangle to flush

     move 30 to ppb-update-width.
     move 15 to ppb-update-height.
 * 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, column 1 of the panel.

     move 1 to ppb-update-start-row.
     move 0 to ppb-update-start-col.

 * 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 pf-flush-panel to ppb-function.
     call "PANELS" using panels-parameter-block.
     if ppb-status not = zero
 *       (code to abort)

Comments:

PF-Flush-Panel has no effect if you specify a panel that is not enabled.

PF-Scroll-Panel (Value 10)

Scrolls a rectangular area of a panel.

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.

You must specify certain data items depending on the bit settings in PPB-Update-Mask:

Parameters:

PPB-Panel-ID                    pic 9(4) comp-x.
PPB-Update-Height               pic 9(4) comp-x.
PPB-Update-Width                pic 9(4) comp-x.
PPB-Update-Start-Row            pic 9(4) comp-x.
PPB-Update-Start-Col            pic 9(4) comp-x.
PPB-Scroll-Direction            pic 9(2) comp-x.
PPB-Scroll-Count                pic 9(4) comp-x.
PPB-Update-Mask                 pic x.
PPB-Buffer-Offset               pic 9(4) comp-x.
PPB-Vertical-Stride             pic 9(4) comp-x.
PPB-Fill-Character              pic x.
PPB-Fill-Attribute              pic x.
text-buffer                    
pic x(n).
attribute-buffer                pic
x(n).

On Entry:

On Exit:

None

Example:

A panel has been defined that is 50 characters wide and 15 rows deep (see Figure 11-4). The handle for this panel is saved in the data item ws-save-panel-id.

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. 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 line in the text and attribute buffers is 50 characters wide).

Figure 11-4: Scrolling Text and Attributes on a Panel

 * Define an update rectangle; that is a block of the panel to
 * scroll. 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, column 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 scrolls up.

     move 0 to ppb-scroll-direction

 * Scroll up 15 lines.

     move 15 to ppb-scroll-count.

 * The panel is 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 the 16th line of the buffers. PPB-Buffer-Offset specifies
 * what character of the buffers to begin with (where 1 is the
 * first character). 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 are seen on the screen as the rectangle scrolls in
 * the enabled panel(set bits 4 and 5 of PPB-Update-Mask).
 * x"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 text-buffer and the
 * attribute buffer is attribute-buffer.

     move pf-scroll-panel to ppb-function.
     call "PANELS" using panels-parameter-block
                         text-buffer
                         attribute-buffer
     if ppb-status not = zero
 *       (code to abort)

Comments:

Panels does not allow you to scroll text and attributes separately.

PF-Write-Panel (Value 11)

Writes to a panel.

Text and attributes you write to the panel are visible on the screen if you use bits 4 and 5 in PPB-Update-Mask and the panel is enabled.

You must specify certain data items depending on the bit settings in PPB-Update-Mask:

Parameters:

PPB-Panel-ID                    pic 9(4) comp-x.
PPB-Update-Height               pic 9(4) comp-x.
PPB-Update-Width                pic 9(4) comp-x.
PPB-Update-Start-Row            pic 9(4) comp-x.
PPB-Update-Start-Col            pic 9(4) comp-x.
PPB-Update-Mask                 pic x.
PPB-Buffer-Offset               pic 9(4) comp-x.
PPB-Vertical-Stride             pic 9(4) comp-x.
PPB-Fill-Character              pic x.
PPB-Fill-Attribute              pic x.
text-buffer                    
pic x(n).
attribute-buffer                pic
x(n).

On Entry:

Example:

This example assumes a panel has been defined that is 50 characters wide and 15 rows deep (see Figure 11-5). The handle for this panel is saved in the data item ws-save-panel-id.

Figure 11-5: Writing Text and Attrbutes to a Panel

This example writes the first 15 rows from the text and attribute buffers to the 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 first character 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). x"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 text-buffer and the
 * attribute buffer is attribute-buffer.

     move pf-write-panel to ppb-function
     call "PANELS" using panels-parameter-block
             ws-text-buffer
             ws-attribute-buffer.
     if ppb-status not = zero
 *       (code to abort)

See Also:

PF-Enable-Panel

PF-Read-Panel (Value 12)

Reads text and attributes from a panel into buffers supplied by your calling program.

Parameters:

PPB-Panel-ID                    pic 9(4) comp-x.
PPB-Update-Height               pic 9(4) comp-x.
PPB-Update-Width                pic 9(4) comp-x.
PPB-Update-Start-Row            pic 9(4) comp-x.
PPB-Update-Start-Col            pic 9(4) comp-x.
PPB-Rectangle-Offset            pic 9(4) comp-x.
PPB-Update-Count                pic 9(4) comp-x.
PPB-Buffer-Offset               pic 9(4) comp-x.
PPB-Update-Mask                 pic x.
PPB-Vertical-Stride             pic 9(4) comp-x.
text-buffer                    
pic x(n).
attribute-buffer                pic
x(n).

On Entry:

On Exit:

None

Example:

This example assumes a panel has been defined that is 10 characters wide and 30 rows deep. The handle for this panel is saved in ws-save-panel-id.

This example reads a portion of this panel, starting from first column of the 7th line, to the end of the panel. Text only (not attributes) is read into a buffer called text-buffer which is assumed to be defined in the Working-Storage Section of the program. The example panel is shown in Figure 11-6.

Figure 11-6: Reading From 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 updates 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 text-buffer, defined
 * as PIC X(240).

     move pf-read-panel to ppb-function.
     call "PANELS" using panels-parameter-block
             text-buffer.
     if ppb-status not = zero
 *       (code to abort)

Comments:

PF-Read-Panel does not behave like an ACCEPT statement; that is, it does not allow the user to input information to a panel. If you want to obtain information from the user, you must use an ACCEPT statement.

You must make sure that the buffers are large enough to accommodate the data that Panels places into them. If they are not large enough, Panels could overwrite information following the buffers in the Working-Storage Section of your program.

PF-Get-Panel-At-Position (Value 13)

Determines if there is a panel at a particular position. If there is, details of the panel's appearance are also returned.

Parameters:

PPB-Panel-Start-Column          pic 9(4) comp-x.
PPB-Panel-Start-Row             pic 9(4) comp-x.
PPB-Panel-ID                    pic 9(4) comp-x.
PPB-Panel-Height                pic 9(4) comp-x.
PPB-Panel-Width                 pic 9(4) comp-x.
PPB-Visible-Height              pic 9(4) comp-x.
PPB-Visible-Width               pic 9(4) comp-x.
PPB-Panel-Start-Column          pic 9(4) comp-x.
PPB-Panel-Start-Row             pic 9(4) comp-x.
PPB-First-Visible-Col           pic 9(4) comp-x.
PPB-First-Visible-Row           pic 9(4) comp-x.

On Entry:

On Exit:

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 pf-get-panel-at-position to ppb-function.
     call "PANELS" using panels-parameter-block.
     if ppb-status not = zero
 *       (code to abort)

Comments:

Use PF-Get-Panel-Info if you know the handle of a panel but want to return information about its appearance.

See Also:

PF-Get-Panel-Info

PF-Set-Panel-Name (Value 14)

Associates a name with the specified panel.

Parameters:

PPB-Panel-ID                    pic 9(4) comp-x.
Panel-Name-Buffer.
    Panel-Name-Length           pic 99 comp-x.
    Panel-Name-Text             pic x(30).

On Entry:

On Exit:

None.

Example:

This example assumes that you have just created a panel, and that you have defined Panel-Name-Buffer in the Working-Storage Section of your program as specified above.

     move 11 to panel-name-length.
     move "Dummy Panel" to panel-name-text.
     move pf-set-panel-name to ppb-function.
     call "PANELS" using panels-parameter-block
                          panel-name-buffer.
     if ppb-status not = zero
 *       (code to abort)

Comments:

Once you have used this function, you can see the name associated with each panel by using the PF-Get-First-Panel and PF-Get-Next-Panel functions.

See Also:

PF-Get-First-Panel
PF-Get-Next-Panel

PF-Get-First-Panel (Value 15)

Returns the identifying handle and information about the panel that was enabled most recently.

Parameters:

PPB-Panel-ID                    pic 9(4) comp-x.
PPB-Panel-Height                pic 9(4) comp-x.
PPB-Panel-Width                 pic 9(4) comp-x.
PPB-Visible-Height              pic 9(4) comp-x.
PPB-Visible-Width               pic 9(4) comp-x.
PPB-Panel-Start-Column          pic 9(4) comp-x.
PPB-Panel-Start-Row             pic 9(4) comp-x.
PPB-First-Visible-Col           pic 9(4) comp-x.
PPB-First-Visible-Row           pic 9(4) comp-x.
Panel-Name-Buffer.
    Panel-Name-Length           pic 99 comp-x.
    Panel-Name-Text             pic x(30).

On Entry:

None

On Exit:

Example:

This example assumes that you have defined Panel-Name-Buffer in the Working-Storage Section of your program as specified above.

     move pf-set-panel-name to ppb-function.
     call "PANELS" using panels-parameter-block
                         panel-name-buffer.
* 
* code to check if the panel is enabled. 
*     if ppb-status not = zero
*       (code to abort)

Comments:

On exit from this function, the most significant bit of Panel-Name-Length is a flag that indicates whether or not the panel is currently enabled - zero indicates that the panel is not enabled, while a non-zero value shows that it is enabled. To check whether this is the case, you should check whether Panel-Name-Length > 127.

If there are no panels when you call PF-Get-First-Panel, PPB-Status contains the value Error-Invalid-ID.

See Also:

PF-Get-Next-Panel
PF-Set-Panel-Name

PF-Get-Next-Panel (Value 16)

Returns the identifying handle and information about the panel that would be the topmost panel if the currently topmost panel were deleted.

Parameters:

PPB-Panel-ID                    pic 9(4) comp-x.
PPB-Panel-Height                pic 9(4) comp-x.
PPB-Panel-Width                 pic 9(4) comp-x.
PPB-Visible-Height              pic 9(4) comp-x.
PPB-Visible-Width               pic 9(4) comp-x.
PPB-Panel-Start-Column          pic 9(4) comp-x.
PPB-Panel-Start-Row             pic 9(4) comp-x.
PPB-First-Visible-Col           pic 9(4) comp-x.
PPB-First-Visible-Row           pic 9(4) comp-x.
Panel-Name-Buffer.
    Panel-Name-Length           pic 99 comp-x.
    Panel-Name-Text             pic x(30).

On Entry:

None

On Exit:

Example:

This example returns the details of all panels that Panels is aware of. The example assumes that you have declared a table in the Working-Storage Section of your program to hold the information, and a data item panel-num to use as a subscript.

*
* Get details of the first panel
*
     move 1 to panel-num
     move pf-get-first-panel to ppb-function
     perform make-panels-call
     if ppb-status not = error-invalid-id
*       (code to abort)
     perform move-values-to-working-storage
     add 1 to panel-num
*
* Get details of all other panels, until ppb-status is
* returned as error-invalid-id.
*
     move pf-get-next-panel to ppb-function
     call "PANELS" using panels-parameter-block
                         panel-name-buffer
     perform until ppb-status = error-invalid-id
         perform move-values-to-working-storage
         add 1 to panel-num
         perform make-panels-call
     end-perform
     ...

 move-values-to-working-storage section.
*
* Move all the exit parameters to the Working-Storage section
* to retain their values.
*
     move ppb-panel-id       to ws-panel-id (panel-num)
     move ppb-panel-height   to ws-panel-height (panel-num)
     move ppb-panel-width    to ws-panel-width (panel-num)
     move ppb-visible-height to ws-visible-height (panel-num)
     move ppb-visible-width  to ws-visible-width (panel-num)
     move ppb-panel-start-column 
                             to ws-panel-start-column (panel-num)
     move ppb-panel-start-row
                             to ws-panel-start-row (panel-num)
     move ppb-first-visible-col
                             to ws-first-visible-col (panel-num)
     move ppb-first-visible-row
                             to ws-first-visible-row (panel-mum)
     move panel-name-buffer  to ws-panel-name-buffer (panel-num)
     move panel-name-length  to ws-panel-name-length (panel-num)
     move panel-name-text    to ws-panel-name-text (panel-num)
     .

 make-panels-call section.
     call "PANELS" using panels-parameter-block
                         panel-name-buffer
     .

Comments:

On exit from this function, the most significant bit of Panel-Name-Length is a flag that indicates whether or not the panel is enabled - zero indicates that the panel is not enabled, while a non-zero value shows that it is enabled. To check whether this is the case, you should check whether Panel-Name-Length > 127.

The only Panels calls that you can use immediately before PF-Get-Next-Panel are PF-Get-First-Panel and other PF-Get-Next-Panel. That is, there must be no other Panels calls between two successive calls to PF-Get-Next-Panel, or between a call to PF-Get-First-Panel and one to PF-Get-Next-Panel.

If there is no next panel when you call PF-Get-Next-Panel, PPB-Status contains the value Error-Invalid-ID.

See Also:

PF-Get-First-Panel
PF-Set-Panel-Name

PF-Get-Panel-Stack (Value 17)

Returns a list of the identifying handles of all enabled panels.

Parameters:

Panels-Order-List           A group item containing: 
    POL-Count                   pic 9(4) comp-x.
    POL-ID                      pic 9(4) comp-x occurs 254.

On Entry:

None

On Exit:

Example:

This example returns a list of the identifying handles of all enabled panels. The example assumes that you have declared Panels-Order-List in the Working-Storage Section of your program as described above.

   move pf-get-panel-stack to ppb-function
   call "PANELS" using panels-parameter-block
                       panels-order-list

Comments:

The first item returned in the list (POL-ID(1)) holds the most recently enabled panel, and so on.

See Also:

PF-Set-Panel-Stack

PF-Set-Panel-Stack (Value 18)

Resets the stack of enabled panels according to the specified list of enabled panels, then redraws the screen.

Parameters:

Panels-Order-List           A group item containing: 
    POL-Count                   pic 9(4) comp-x.
    POL-ID                      pic 9(4) comp-x occurs 254.

On Entry:

On Exit:

None

Example:

The following example shows how you could use the PF-Get-Panel-Stack and PF-Set-Panel-Stack functions together to save the state of an application's panels, before changing the panels, then restoring the panels to their original state.

The example shows extracts of a main program that calls a subprogram, where the state of the main program's panels is saved prior to calling the subprogram and restored on return. The subprogram requires only one panel to be displayed, a company logo, which is displayed by the main program.

 working-storage section.
 01  panels-order-list.
     03  pol-count             pic 9(4) comp-x.
     03  pol-id                pic 9(4) comp-x occurs 254.
 01  save-panels-order-list    pic x(510).
 01  company-logo-panel-id     pic 9(4) comp-x.
 ...

 procedure division.
 ...

 call-subprogram section.
 ...

* Before calling the subprogram, get a copy of the current stack
* of panels.
     move pf-get-panel-stack to ppb-function
     perform make-panels-call

* Now save this copy of the stack.
     move panels-order-list to save-panel-order-list

* Next, remove all of the main program's panels from the
* display, except for the panel showing the company logo.
     move 1 to pol-count
     move company-logo-panel-id to pol-id(1)

     move pf-set-panel-stack to ppb-function
     perform make-panels-call

* The Stack is now empty, except for the company logo, so call
* the subprogram.
      call "SUBPROG"

* On return from the subprogram, restore the program's panels
* to their state prior to the subprogram call.
     move pf-set-panel-stack to ppb-function
     perform make-panels-call
     ...

 make-panels-call section.
     call "PANELS" using panels-parameter-block
                         panels-order-list
     .

Comments:

Any panel not specified in POL-ID is disabled, while any panel that is specified in POL-ID is enabled and displayed.

See Also:

PF-Get-Panel-Stack

PF-Create-Panel-With-Shadow (Value 19)

Creates a panel with a shadow effect. The panel's window is created disabled; that is, it is not visible.

Parameters:

PPB-Panel-Height                pic 9(4) comp-x.
PPB-Panel-Width                 pic 9(4) comp-x.
PPB-Visible-Height              pic 9(4) comp-x.
PPB-Visible-Width               pic 9(4) comp-x.
PPB-Panel-Start-Column          pic 9(4) comp-x.
PPB-Panel-Start-Row             pic 9(4) comp-x.
PPB-First-Visible-Col           pic 9(4) comp-x.
PPB-First-Visible-Row           pic 9(4) comp-x.
PPB-Panel-ID                    pic 9(4) comp
PPB-Update-Mask                 pic x.
PPB-Fill-Character              pic x.
PPB-Fill-Attribute              pic x.

On Entry:

On Exit:

Example:

This example creates a panel that is 25 characters wide by 8 lines high. This panel starts on line 1, column 1 of the screen. The window into this panel starts on the first line and first column of the panel. This window is 25 characters wide by 6 rows deep.

The shadowing on the panel is one character wide, and is seen as a gray band.

Figure 11-7: Creating a Panel

 * Panel size is 20 characters wide by 15 lines 

     move 25 to ppb-panel-width. 
     move  8 to ppb-panel-height. 

 * The window starts on screen line 1, 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 0 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 25 to ppb-visible-width.
     move  6 to ppb-visible-height.

 * The window starts on the first line and column of the panel.
 * Remember that 0,0 is the top left corner of the panel. 

     move 0 to ppb-first-visible-row.
     move 0 to ppb-first-visible-col.

 * Specify the shadowing for the panel

     move 0 to ppb-update-mask
     move space to ppb-fill-character
     move gray  to ppb-fill-attribute

 * 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.

Comments:

Panels allocates an area of memory for the new panel based on its size. The number of bytes of memory used by a shadowed panel is determined as follows:

4 * PPB-Panel-Height * PPB-Panel-Width

The size of the new panel can be larger than the screen, but you must observe the following:

• PPB-Panel-Width must not be greater than 2000.

• 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 with a shadow, you can change any of its variables except its width, height, and shadow details. You do this using PF-Shift-Panel. The newly created panel is filled with the current backdrop character and attribute. The shadowing effect on a shadowed panel is not transparent.

See Also:

PF-Create-Panel
PF-Shift-Panel

11.2.6 Using Panels with Adis

The Adis (ACCEPT/DISPLAY) module in your COBOL software allows you to use ACCEPT and DISPLAY statements in a program that includes Panels. See the chapter Adis for information about this module. The example program panelex2 supplied with your software shows how Adis can be used with Panels. The Panels Tutorial, pantutor.cbl, also gives examples of using Adis with Panels.

11.2.6.1 Considerations When Using Adis and Panels

As you use Panels with Adis, you should be aware of the following points:

• Only enhanced ACCEPT and DISPLAY statements (see your Language Reference) can be directed to a panel. You could encounter problems if you use standard ANSI ACCEPT and DISPLAY statements to write directly to the screen. The same is true if you use the x"B7" COBOL system library routine or the call-by-name screen handling routines with Panels.

• The positions specified in AT, LINE and COLUMN clauses are relative to the top left corner of the current panel and not to the screen.

• You can create any number of panels , and can have up to 254 enabled at one time. Six of these are used by Adis when Adis is used with Panels.

11.2.6.2 Overview of Adis Functions for Panels

The available Adis functions for use with Panels are:

11.2.6.3 CALL Syntax

The syntax for using these Adis functions is:

call x"AF" using function-code                  parameter

where the parameters are:

Notes:

• All Adis calls must have a second parameter even though its contents are sometimes ignored.

• If an error occurs while executing this call, parameter returns a value of 255.

11.2.6.4 Adis Function Descriptions

The following sections describe the Adis functions available for use with Panels.

Disable or Enable Adis Indicators

When you use x"AF" function 49 to tell Adis that you are using Adis and Panels together, the function creates six predefined panels for you. Four of the panels are used to display Adis indicators (Insert, Replace, Auto-skip, and Off-end-of-field indicators). Another field is used for displaying Adis error messages. You might want to suppress these messages when you are using Panels.

You can disable and enable Adis error messages and indicators with this function.

Syntax:

call x"AF" using function-code                  parameter

Parameters:

Initialize Adis to Use Panels

You use this function to create a panel with the same dimensions as your screen. This panel is automatically enabled and is space filled with white on black attributes. The screen is cleared.

You execute this call only once at the beginning of your program.

Syntax:

call x"AF" using init-panels-fn                  parameter

Parameters:

Example

 01 init-panels-function  pic x comp-x value 49.
 01 parameter             pic x. 
       ...
     call x"af" using init-panels-function
                      parameter

The panel created by this call is automatically enabled, clearing the previous contents from the screen. It contains spaces as the default backdrop character. The default attribute setting is white on a black background. All ACCEPT and DISPLAY statements are directed to this panel unless another panel is specified. See the section Specify Panel for ACCEPT/DISPLAY for information on how to do this. The panel identifier (Panel-ID) value of the panel created by this call is always 0.

This call creates six panels for use by Adis. All but the first of the following list are on the bottom line of your screen.

• A full screen panel.

• An Adis error message panel, in columns 1 through 77.

• A one-character panel for the Insert indicator.

• A one-character panel for the Off-end-of-field indicator.

• A one-character panel for the Auto-skip indicator.

• A one-character panel for the Replace indicator.

See the chapter Adis Configuration Utility (Adiscf) for more information about these indicators.

These six panels cannot be used by your program. See the section Enable or Disable Adis Indicators for information on enabling or disabling them.

Specify Panel for ACCEPT/DISPLAY

This function tells Adis which panel is to be used for all subsequent ACCEPT and DISPLAY statements in your program. All ACCEPT and DISPLAY statements are directed to this specified panel until you make another call to this function.

Syntax:

call x"AF" using specify-panel-fn                 
work-panel-ID

Parameters:

Comments:

Your program must create a panel before you can execute this call, unless you want to work with the default panel created by Adis.

If the specified panel does not exist, the value 255 is returned in specify-panel-function, and the previously specified panel is used for the ACCEPT and DISPLAY statements.

If you direct an ACCEPT statement to a panel, the panel is enabled automatically so that the visible portion is not obscured by another panel. If the panels window is smaller than the panel, and the cursor position resulting from the ACCEPT is not currently visible, Adis positions the window so that the text at the cursor becomes visible. A DISPLAY statement directed to a panel is the same as the PF-Write-Panel when you update both text and attributes.

Example

 01 specify-panel-function    pic x comp-x value 56.
 01 work-panel-id             pic xx comp-x.
       ...
*    (Code to create panel and move its identifier into
*    work-panel-id)
       ...
     call x"af" using specify-panel-function
                      work-panel-id.

Enable or Disable Delayed Update

This function allows you to execute several DISPLAY statements without updating the screen each time one is executed. You then execute only one call to update the screen with all of them, often resulting in a faster updating process.

Screen updates are delayed until either you execute an ACCEPT statement or you use this call to update the screen and re-enable screen updating (see below).

Syntax:

call x"AF" using control-update-fn                 
control-update-param

Parameters:

Comments:

The result of executing an ACCEPT statement is the same as executing this call with parameter set to 0. Therefore, after you execute an ACCEPT statement, you must execute another call to this function with parameter set to 1 if you still want to use the delayed update method.

Example

 01 control-update-function     pic x comp-x value 57.
 01 control-update-parameter    pic x comp-x. 
       ...
     move 1 to control-update-parameter.
     call x"af" using control-update-function
                      control-update-parameter.
       ...
* Any DISPLAY statements here are not reflected on the screen
 ...
     move 0 to control-update-parameter.
     call x"af" using control-update-function
                      control-update-parameter.
* Now all the previous displayed information is visible.

Suspend Use of Panels by Adis

This function allows you to suspend the use of Panels by Adis, in order to allow direct screen writes where Panels is not required.

You must have previously used x"AF" function 49 to initialize Adis to use Panels. See the section Initialize Adis to use Panels for details of doing this.

Syntax:

call x"AF" using suspend-function                 
suspend-parameter

Parameters:

Comments:

If Adis has not been initialized to work with Panels, the value 255 is returned in suspend-function.

Example

 01 suspend-function     pic x comp-x value 62.
 01 suspend-parameter    pic x comp-x.
       ... 
*   (Code to set up Adis to use Panels) 
       ... 
* Suspend Panels working 
     move 0 TO suspend-parameter. 
     call x"af" using suspend-function
                      suspend-parameter.
       ...
* Reactivate Panels working
     move 1 TO suspend-parameter.
     call x"af" using suspend-function
                      suspend-parameter.

Return Status of Panels Use by Adis

This function allows you to obtain details of how Adis is using Panels for ACCEPT and DISPLAY statements.

Syntax:

call x"AF" using get-status-fn                 
get-status-param

Parameters:

Example

 01 get-status-function      pic x comp-x value 63.
 01 get-status-parameter.
    03 panels-usage-flag     pic x comp-x.
    03 panels-status-flag    pic x comp-x.
    03 current-panel-id      pic xx comp-x.
       ...
     call x"af" using get-status-function
                      get-status-parameter.
     if panels-usage-flag = 0
         display "Adis is not using Panels."
     else
         if panels-status = 0
             display "Use of Panels by Adis is suspended."
         else
             display "Use of Panels by Adis is active."
             display "The ID of the PANEL being used by Adis is"
                     current-panel-id
         end-if 
     end-if.

11.2.7 Panels Error Codes

This section lists the values that can be returned in the status field PPB-Status by a call to Panels. The mnemonics are shown in the order in which they appear in panlink.cpy.

PE-No-Error (Value 0)

The function requested completed successfully.

PE-Not-Created (Value 1)

The panel required does not exist. This value is returned if you attempt to perform a function on a panel that has not yet been created. You must create a panel before it can be used.

PE-Invalid-ID (Value 2)

The panel identifier is outside the range of valid panel identifiers. The maximum number of panels that can be visible at one time is 254.

PE-Invalid-Parameters (Value 3)

The update parameters supplied do not define an area that is inside the panel. The specified values of PPB-Update-Start-Row or PPB-Update-Start-Col are outside the panel; that is, they are greater than the height and/or width of the panel.

PE-Invalid-Function (Value 4)

The function number specified in PPB-Function is not a valid function number.

PE-No-Room-For-Panel (Value 5)

The program is trying to create too many panels. The maximum number of panels have already been created. This error occurs on a call to PF-Create-Panel if the maximum number of panels (65534) has already been created.

PE-Panel-Too-Large (Value 6)

The panel specified is too large. This value is returned if the program has specified a panel size that is too large. This will be due to one of the following reasons:

1. The program is trying to create a panel that is too large, that is: PPB-Panel-Width *PPB-Panel-Height > 65535.

2. The width of the panel is greater than 2000 characters.

3. There is insufficient memory available to hold the panel text and attribute buffers.
   

PE-Invalid-Direction (Value 7)

The value supplied in PPB-Scroll-Direction is not in the range 0 through 3.

PE-Invalid-Scroll-Count (Value 8)

You are trying to scroll too many rows or columns. The specified value of PPB-Scroll-Count is greater than the number of rows or columns in the panel (depending on the direction of scroll).

PE-Cannot-Initialise (Value 9)

Panels cannot initialize. This is a fatal error which occurs only on the first call to Panels made by a program in your system. It means that for some reason, Panels cannot initialize.

11.2.8 Packaging a Panels Application

This section shows you the files you need to link in with your program if it uses Panels.

DOS, Windows and OS/2:
If your program uses Panels without Adis, the only file you must link in on DOS, Windows or OS/2 is panels.obj.

If your program makes use of Adis function as well as Panels, you must link in the following on DOS, Windows or OS/2:

• panels.obj

• adis.obj

• adisinit.obj

• adiskey.obj

UNIX:
If your program uses Panels or Adis, all the required routines are automatically linked in when you build an executable program.

Using Screens

Using Panels