Keyboard Configuration Utility (Keybcf)

COBOL System Library Routines

Chapter 5: 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.

Panels takes care of maintaining the areas of the screen that are overlaid by another window automatically. It is for programmers who require high performance screen handling facilities.

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

5.1 What is a Panel?

The basic concept in Panels is the panel. The panel 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. Any number of 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.

The diagram below represents the relationship among screen, window and panel.

5.2 Using Panels

You use Panels as follows:

• You call the Panels module using the CALL statement.

  The CALL statement must include the panels-parameter-block, which contains all the fields you define when you are working with Panels.

  You include the text-buffer and attribute-buffer parameters in the CALL statement, but you need this only if you are writing to, reading from, or scrolling a panel.

  When a panel is created or the window is moved or resized, the size of the window might be reduced if one of the specified size cannot be created. This is known as clipping the height and width of the window.

5.2.1 Calling Panels

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

See also:

Panels Parameter Block, To Specify Attributes for a Panel.

5.2.2 Text and Attributes 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 three types of encoding:

• Standard PC monochrome attribute encoding. This is the default encoding for Panels for systems with a monochrome display.
• Standard PC color attribute encoding. This is the default encoding for Panels for systems with a color display.
• User selected or generic attribute encoding for all types of display.

You can determine the type of encoding used by Panels by calling an RTS library routine. See the release notes for details.

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.

5.2.2.1 To Specify Text for a Panel

Use one of the three methods below:

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

5.2.2.2 To Specify Attributes for a Panel

Use one of the three methods below:

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

5.2.2.3 To Specify Attributes Without Specifying Text

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

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

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-Co       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-Coun        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 Parameters for Panels Functions.

The fields relevant to a particular function are explained in Panels Functions.

5.3.1 Parameters for Panels Functions

The parameters required for the Panels functions are defined in the Panels Parameter block in the copyfile panlink.cpy.

5.3.2 Description of Parameters

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-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-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-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-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 topic Panels Functions.

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

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.

See also:

PPB-Update-Count, PPB-Update-Width, PPB-Update-Height.

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

See also:

PPB-Scroll-Direction.

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:

See also:

PPB-Scroll-Count.

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 topic Panels Error Codes.

We recommend you test the status field after every call to Panels.

See also:

Panels Error Codes.

PPB-Update-Count

This field specifies the number of characters to be updated within a specified rectangle. You can choose to update an irregular-shaped area of a rectangle by specifying values for both the PPB-Update-Count and PPB-Rectangle-Offset fields.

If you update an entire rectangle, you set this field to the resulting value of PPB-Update-Width multiplied by PPB-Update-Height.

See also:

PPB-Rectangle-Offset, PPB-Update-Height, PPB-Update-Width.

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.

See also:

PPB-Rectangle-Offset; PPB-Update-Count; PPB-Update-Width.

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.

See also:

PF-Flush-Panel, PF-Scroll-Panel, PF-Write-Panel, PF-Read-Panel, PPB-Fill-Attribute, PPB-Fill-Character.

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.

See also:

PPB-Rectangle-Offset, PPB-Update-Count, PPB-Update-Height.

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

5.4 Clipping a Panel

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.

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

5.5 Panels Functions

You can execute a number of functions when using Panels. The functions are:

PF-Create-Panel (Value 3)

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

Parameters:

On Entry:

On Exit:

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.

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:

PPB-Panel-Width, PPB-Panel-Height, PF-Shift-Panel, Panels Error Codes.

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.

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

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:

On Entry:

On Exit:

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.

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, Panels Error Codes.

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.

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

PF-Delete-Panel (Value 6)

Deletes a panel from the system.

Parameters:

On Entry:

On Exit:

None

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.

If you delete a panel that was enabled, it disappears from the screen.

See also:

Panels Error Codes.

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)

PF-Disable-Panel (Value 8)

Disables a panel, making it invisible.

Parameters:

On Entry:

On Exit:

None

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.

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)

PF-Enable-Panel (Value 7)

Enables a panel, making it visible on the screen.

Parameters:

On Entry:

On Exit:

None

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.

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)

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.

Parameters:

On Entry:

On Exit:

None

Comments:

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

See also:

Overview - Panels, Panels Parameter Block, PPB-Update-Mask.

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. The handle of the original panel is assumed to be saved in data item ws-save-panel-id.

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

PF-Get-First-Panel (Value 15)

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

Parameters:

On Entry:

None

On Exit:

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-Set-Panel-Name, PF-Get-Next-Panel.

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)

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:

On Entry:

None

On Exit:

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-Set-Panel-Name, PF-Get-First-Panel.

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

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:

On Entry:

On Exit:

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.

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)

PF-Get-Panel-Info (Value 5)

Finds out the size and position of an existing panel.

Parameters:

On Entry:

On Exit:

See also:

PF-Create-Panel.

Example:

This example returns information about the panel whose panel identifier is saved in the variable ws-save-panel-id.

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

PF-Get-Panel-Stack (Value 17)

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

Parameters:

On Entry:

None

On Exit:

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.

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.

PF-Get-Screen-Info (Value 0)

Returns information about the size of the current screen.

Parameters:

On Entry:

None

On Exit:

Comments:

You can change the backdrop character and attribute using PF-Set-Screen-Backdrop.

See also:

PF-Set-Screen-Backdrop.

Example:

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

PF-Read-Panel (Value 12)

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

Parameters:

On Entry:

On Exit:

None

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.

See also:

PPB-Update-Mask.

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

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

PF-Redraw-Screen (Value 2)

Refreshes the contents of the entire screen.

Parameters:

None

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.

Example:

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

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:

On Entry:

On Exit:

None

Comments:

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

See also:

Overview - Panels, PPB-Update-Mask.

Example:

A panel has been defined that is 50 characters wide and 15 rows deep. 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).

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

PF-Set-Panel-Name (Value 14)

Associates a name with the specified panel.

Parameters:

On Entry:

On Exit:

None.

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.

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-parameteer-block
       panel-name-buffer.
       if ppb-status not = zero
   *          (code to abort)

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:

On Entry:

On Exit:

None

Comments:

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

See also:

PF-Get-Panel-Stack.

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

PF-Set-Screen-Backdrop (Value 1)

Changes the current backdrop character and attribute.

Parameters:

On Entry:

On Exit:

None

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.

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)

PF-Shift-Panel (Value 4)

Moves a window and/or changes its size.

Parameters:

On Entry:

On Exit:

None

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-Panel, PF-Get-Panel-Info, PF-Enable-Panel.

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)

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:

On Entry:

See also:

PF-Enable-Panel, Overview - Panels, PPB-Update-Mask.

Example:

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

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)

5.6 Using Adis Functions with Panels

The Enhanced ACCEPT/DISPLAY syntax (Adis) enables you to use ACCEPT and DISPLAY statements in a program that includes Panels. It is worth considering that:

• Only enhanced ACCEPT and DISPLAY statements 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.

5.6.1 Adis Functions

The following Adis functions are available for use with Panels:

• 1 Enables or disables Adis indicators or error messages.
• 49 Initializes Adis for use with Panels.
• 56 Specifies the panel to which you direct the ACCEPT and DISPLAY statements.
• 57 Updates the screen with several DISPLAY statements using only one call.
• 62 Suspends the use of Panels by Adis.
• 63 Returns the status of Panels' use by Adis.

Disable or Enable Adis Indicators - x"AF" Function 1

The x"AF" function 1 enables and disables Adis error messages and 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.

Syntax:

call x"AF" using   function-code
                   parameter

Parameters:

Initialize Adis to Use Panels - x"AF" Function 49

The x"AF" function 49 creates 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-fn    pic x comp-x value 49.
01 parameter         pic x.
            ...
    call x"af" using init-panels-fn
                     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 topic 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 also:

Disable or Enable Adis Indicators - x"AF" Function 1

Specify Panel for ACCEPT/DISPLAY - x"AF" Function 56

The x"AF" function 56 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-fn    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-fn
work-panel-id.

See also:

PF-Write-Panel.

Enable or Disable Delayed DISPLAY - x"AF" Function 57

The x"AF" function 57 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 you either execute an ACCEPT statement or 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-fn       pic x comp-x value 57.
01 control-update-param    pic x comp-x.
...
move 1 to control-update-param.
call x"af" using control-update-fn
control-update-param.
            ...
* Any DISPLAY statements here are not reflected on the screen
...
move 0 to control-update-param.
call x"af" using control-update-fn
control-update-param.
* Now all the previous displayed information is visible.

Suspend Use of Panels by Adis - x"AF" Function 62

The x"AF" function 62 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 initialized Adis to use Panels using x"AF" function 49.

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 Used by Adis - x"AF" Function 63

The x"AF" function 63 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-fn         pic x comp-x value 63.
01 get-status-param.
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-fn
get-status-param.
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.   

5.6.2 Calling Adis Functions

The syntax for using these Adis functions is:

call x"AF" using    function-code
                    parameter

Parameters:

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.

See also:

Panels Functions, Parameters for Panels Functions.

5.7 Packaging a Panels Application

If your program uses Panels without Adis, link in panels.obj.

If your program makes use of Adis function as well as Panels, link in the following:

• panels.obj
• adis.obj
• adisinit.obj
• adiskey.obj

5.8 Frequently Used Terms in Panels

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.

5.9 Panels Error Codes

This topic 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-Parameter (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.

See also:

PPB-Status.

Cannot open HTML file

• An attempt to open an HTML file was unsuccessful. Either you do not have a World Wide Web browser installed on your system, or an association has not been set up between your browser and the .htm file extension.

  Net Express includes a World Wide Web browser, Microsoft Internet Explorer, which you can install from the Net Express CD. You can use any other browser except that to to view the online books fully, you require a Web browser that is capable of displaying frames, such as Microsoft Internet Explorer.

Keyboard Configuration Utility (Keybcf)

COBOL System Library Routines