GDDM and AP126

Transcribed from the printed issue; not yet reviewed. Read it in the PDF of the issue, page 109

1. Abstract.¶

Full screen management is in many ways the natural way for APL to communicate with the user. The screen looks like a window onto an APL array, why not use it as such? In the IBM world, full screen management is limited to the use of auxiliary processors (APs), usually the Graphical Data Display Manager (GDDM) AP – AP126.

In order to implement efficient, easily used systems, screen dialogue must be managed as efficiently as possible in order to provide adequate response times. This article shows that functions provided by GDDM can be easily used to improve the efficiency of screen dialogues. A future article will discuss the use of functions provided by GDDM R4.0 and by AP126 itself.

2. Introduction – Facilities Discussed.¶

The facilities discussed fall into two basic categories:

• Those integral to GDDM.
• Additional facilities provided by AP126.

The facilities provided by GDDM are available to any program using GDDM (even those not written in APL), the power of APL makes these especially easy to use. The extra functions provided by AP126 are unique to the APL environment. This article discusses those functions provided by GDDM; it is hoped another article will describe the use of the facilities provided by AP126, and additional features of GDDM (R 3.0 and 4.0) which are of use in the development of complex dialogues.

2.1 Facilities provided by GDDM.¶

The following facilities provided by GDDM are not commonly used, and will be the subject of this discussion:

• Use of logical pages (all GDDM releases)
• Logical pages larger than the terminal (GDDM R3.0 and higher)

The discussion applies specifically to VS APL R4.0, running under MVS/SP and TSO/E, but should apply to other operating systems too, since no file handling is involved.

2.2 Facilities provided by AP126¶

The additional facilities available using AP126 are referred to in the VS APL Terminal Users Guide as ‘AP126 Service Requests’. There are 10 of these, given call values from -1 to -10, the majority of these are not of particular use in application development. The most useful services are mentioned here for the sake of completeness, but are not discussed in detail in this article.

Service -8 (Query subset of fields for modification), allows an application to read data from the screen as required by the application, rather than all at once. More importantly, it also allows only modified fields to be read rather than all fields on the screen.

Service -9 (Query current hardcopy destination), allows an application to check for a currently open printer. A printer may therefore be left ‘open’ between print requests, avoiding the large overhead of being ‘opened’ and ‘closed’ repeatedly.

Service -10 provides a useful method for implementing graphics in a system. This service request allows the Interactive Chart Utility (ICU) to be invoked from APL, using APL vectors or arrays of numbers as the data to be charted.

3. Logical Pages.¶

The usual way of organising a full screen dialogue can be summarised as follows:

DIALOGUE:

• DISPLAY a panel
• READ the panel
• VALIDATE the data
• PROCESS the data
• REPEAT

This concept seems perfectly adequate for managing a screen dialogue, until the overheads involved in the DISPLAY process are considered. For the sake of clarity, the DISPLAY process can be broken down further:

DISPLAY:

• VALIDATE the format array
• FORMAT the screen buffer
• WRITE fixed text (prompts etc)
• WRITE dynamic text (date, time etc)
• WRITE default input values
• TRANSMIT panel to screen

If the panel format could be stored in some way, so that it only has to be re-sent to the terminal, the first three processes could be omitted from the DISPLAY process (after the first DISPLAY). The use of logical pages allows precisely this. Each screen format, with its fixed text, can be placed on a separate page, and restored to the terminal as required. The new DISPLAY process could be summarised as follows:

DISPLAY:

• GET page
• WRITE dynamic text
• WRITE default input values
• TRANSMIT panel to screen

The GET process either creates and formats a new page, or re-selects an existing page as required.

GET:

• IF page EXISTS
  • SELECT page
• ELSE
  • CREATE page
  • VALIDATE the format array
  • FORMAT the screen buffer
  • WRITE fixed text (prompts etc)

3.1 Managing Logical Pages.¶

The use of logical pages does introduce the problem of management of the pages. This problem can be broken into two parts:

• Selection of pages for display of new panels.
• Re-selection of existing pages to re-display panels.

The first problem is one of selecting a page not previously used, the second is one of selecting the correct page from a list of existing pages. The examples that follow assume that a share with AP126 has already been established, using the variables:

• CTLs – the AP126 control variable.
• DATs – the data variable associated with CTL126.

3.2 Creating New Logical Pages.¶

GDDM has a function which returns a page number not currently in use – FSQUPG (FS – Full Screen, Q – Query, UPG – Unique PaGe. AP126 Code 307). This function returns the highest possible unused page number. The first call returns page number (-1)+2*31, the highest 4 byte integer.

Note: In early versions of release 3.0 of GDDM, the FSQUPG function returns LOW page numbers first, there is a PTF to correct this error.

A major benefit of using the FSQUPG function, is that no matter many pairs of variables are shared with AP126, unique page numbers are always returned. Thus several applications (systems, utilities etc), all using different sets of shared variables, can run in the same workspace without risk of using pages already acquired by other facilities. This principle extends to using GDDM with the APL Session Manager, which uses page number 1001.

Once the unique page number has been found, the page must be created. This is performed using the FSPCRT function (P – Page, CRT – CReaTe. AP126 code 302). The arguments to the FSPCRT function are the page number, the depth and width of the page, and the page type. This last parameter is ignored by GDDM release 4.0, but is required for compatibility with earlier releases of GDDM. A function to query for and create a page with a new page number (CNPAGE) is listed in appendix A.

The act of creating a page causes the new page to become current, so the panel format/write activities can proceed normally. Once complete, the panel can be displayed and read in the normal manner, all screen I/O functions addressing the current GDDM page.

3.3 Re-displaying Existing Pages.¶

Once a page/panel couple has been formatted and displayed, the only activity that has to occur before re-display of the page is changing the current page number to the one containing the required panel. To do this effectively, a method of relating panel identities (names, numbers or some other ID) to GDDM page numbers must be used.

The IBM supplied workspace FSC126 allows panels to be designed, each panel having a name recognised by all the utility functions in the workspace. The names can easily be used to build a table relating panel names to page numbers. When a panel is displayed for the first time (ie its page is created), the panel name is appended to the bottom of the table, and the page number is appended to the vector of page numbers. The index of the name in the table can then be used to reference the page number vector. Once the page number has been looked up, the page can be reselected by using the FSPSEL function (P – Page, SEL – SELect. AP126 code 305). The FSPSEL function takes the page number to be selected as its only argument.

A function to perform these actions is shown in appendix A (CSPAGE), the function either selects an existing page, or creates a new page if required. This function could be combined with IBM’s DISPLAY function (from FSC126) if the new page was to be formatted. An example of this is shown in the HOWTO function in appendix A. Note, the code in the REDISP function is specific to the use of the utilities provided by the FSC126 workspace. This function would have to be changed if different screen management utilities were to be used.

It must be ensured that the panel name table and the page vector are nullified whenever GDDM is re-initialised. The easiest way to ensure this is to reshape the table and vector into nulls in the function run as the latent expression in the workspace.

3.4 Integrating with Existing Systems.¶

The above discussion shows that it is relatively easy to implement paging techniques within an existing screen management system such as that provided in the FSC126 workspace. The only change required is to ensure the correct page is selected before any screen I/O processing occurs.

In most cases, it will be possible to combine functions using logical paging with functions that do not in the same workspace. This is because, by default, page 0 is used. Functions using paging MUST ensure that the default page (page 0) is re-selected after their processing is complete.

4. Large GDDM Logical Pages¶

From release 3.0 onwards, GDDM allows the use of pages which are longer than the physical terminal. Pages wider than the physical terminal are not supported. Using long pages allows vertical scrolling to be performed very easily. GDDM only requires the line to be placed at the top of the terminal to be passed as an argument to the FSPWIN function (P – Page WIN – WINdow. AP126 code 309). If the bottom or top of the logical page would appear in the middle of the physical page, GDDM adjusts the position so that the logical top/bottom coincides with the physical top/bottom.

The use of long pages reduces the need to re-write text to the page every time a scroll operation is performed. The AP need only be invoked to perform the scrolling activity, not to perform I/O to the logical page. If some of the text has to be refreshed on the page then the correct GDDM functions must be invoked to perform this.

4.1 Using Large Logical Pages¶

Large pages will be of most use for browsing APL objects, rather than for activities requiring text to be refreshed as lines are inserted, deleted or changed by the user. Data being browsed does not need to be refreshed. Even so, if a very simple editor is being used, which does not allow lines to be deleted or inserted from the text, the use of a large page will make the editor more efficient by removing the need to refresh text on the page.

Using screen sized pages, a BROWSE function can be summarised as follows:

BROWSE:

• GET browse panel
• WRITE a panel full of text
• READ the panel
• SCROLL text

The SCROLL function is changed by the use of long pages:

SCROLL: (normal page size)

• CALCULATE new top line
• WRITE new panel of text

SCROLL: (long pages)

• CALCULATE new top line
• POSITION window

When using long pages, all the text is written to the panel during the initialisation stage, not just one panel full. This increase in panel I/O is offset by reductions during scrolling activity.

4.2 Horizontal Scrolling¶

Logical pages wider than the physical screen size are not supported by GDDM. The limitations imposed by this restriction can be obviated by allowing horizontal scrolling to occur only in units of one screen width. The BROWSE function must create sufficient pages to contain the width of the text being browsed. Scrolling horizontally then simply becomes a matter of selecting the the correct logical page. This is a more efficient process than continually performing I/O operations to the same logical page.

The ‘page mode’ scrolling can also be used for vertical scrolling in releases of GDDM not supporting large logical pages. An ideal application for this type of browse function is to preview a paginated report. Whether all pages should be formatted in advance is application dependent and will typically depend on the volume of text being browsed.

For a ‘page mode’ browse function allowing both vertical and horizontal scrolling, the SCROLL function becomes:

BROWSE:

• CALCULATE new top line
• CALCULATE new horizontal page
• GET page
• POSITION window

The GET function is described in section 3.

5. Conclusions.¶

The use of logical pages can make a considerable difference to the speed of dialogues in systems using GDDM for screen management. In addition, the use of logical pages is quite straightforward to implement within a set of existing dialogue management utilities.

By removing the need to re-format a panel every time it is to be displayed, response times can be improved by as much as 50%. Logical pages can also be of use elsewhere in full-screen dialogues, for example when implementing ‘browse’ or ‘edit’ utilities, enabling scrolling to be carried out extremely rapidly.

Appendix A¶

FSCMD¶

    ∇ RC←DAT ∆FSCMD CTL
[1]   ⍝ Version: 29.11.85      FN: Communicate with AP126 shared vars
[2]   ⍝ DAT - Character vector     Value for DAT shared variable
[3]   ⍝ CTL - Numeric vector       Value for CTL shared variable
[4]   ⍝ RC  - Numeric vector       Value returned by CTL shared variable
[5]    DATs←DAT
[6]    CTLs←CTL
[7]    RC←1↓CTLs
    ∇

CNPAGE¶

    ∇ PAGE←CNPAGE;FSPCRT;FSQUPG;RC
[1]   ⍝ Version: 29.11.85      FN: Query for and create new page
[2]   ⍝ PAGE - Numeric vector     Page number or null if error
[3]   ⍝ Assign GDDM function codes
[4]    FSQUPG←307
[5]    FSPCRT←302
[6]   ⍝ Query for unused page number
[7]    RC←'' ∆FSCMD FSQUPG
[8]   ⍝ Store the page number returned
[9]    PAGE←1↑4↓RC
[10]  ⍝ Create the page with default size.
[11]   RC←(2↑RC),2↑'' ∆FSCMD FSPCRT,PAGE, 0 0 1
[12]  ⍝ Return page number if all codes from GDDM/AP126 are zero
[13]   PAGE←(∧/0=RC)/PAGE
    ∇

CSPAGE¶

    ∇ RC←CSPAGE PANEL;FSPSEL;MAX;PAGE
[1]   ⍝ Version: 29.11.85      FN: Select/Create page based on PANEL
[2]   ⍝ PANEL - Character vector     Panel name to be created/selected
[3]   ⍝ RC    - Numeric vector       Return code (0=Fail 1=New page 2=Old page)
[4]   ⍝ ptab  - Global table of panel names
[5]   ⍝ pvec  - Global vector of page numbers
[6]    MAX←(⍴PANEL)⌈¯1↑⍴ptab
[7]   ⍝ Check if PANEL is already in <ptab>
[8]    PAGE←((((1↑⍴ptab),MAX)↑ptab)∧.=MAX↑PANEL)/pvec
[9]    →(0=⍴PAGE)/pc
[10]  ⍝ Page number non zero, select it.  Assign GDDM command code.
[11]   FSPSEL←305
[12]  ⍝ Page exists, reselect and return code=2
[13]   RC←2×∧/0=2↑'' ∆FSCMD FSPSEL,PAGE
[14]  ⍝ Run dialogue manager specific code to re-init global vars etc.
[15]   REDISP PANEL
[16]   →0
[17]  ⍝ No page number returned, create page.  Exit if error
[18]  pc:PAGE←CNPAGE
[19]  ⍝ Return 0 if no page number returned, or 1 to indicate new page.
[20]   →0 IF~RC←0≠⍴PAGE
[21]  ⍝ Update <pvec> and <ptab>, and exit
[22]   pvec←pvec,PAGE
[23]   ptab←(((1↑⍴ptab),MAX)↑ptab),[1]MAX↑PANEL
    ∇

REDISP¶

    ∇ REDISP PANEL;LL
[1]   ⍝ Version: 09.12.85      FN: Reset globals used by FSC126 utilities
[2]   ⍝ PANEL - Character vector   Panel name
[3]   ⍝ Flag no fields as modified
[4]    rmod←⍳0
[5]   ⍝ Check for lable array for this panel
[6]    →ex IF 2≠⎕NC 'LL',,PANEL
[7]   ⍝ Set up label globals (eXPAND and cN are utilities from FSC126)
[8]    LL←eXPAND⍎'LL',,PANEL
[9]    nlabel←cN label←((1↑⍴LL),6)↑LL
[10]   →0
[11]  ⍝ Expunge label global, to indicate no labels found
[12]   LL←⎕EX 'label'
    ∇

HOWTO¶

    ∇ RC←HOWTO;INT;PANEL
[1]   ⍝ Version: 29.11.85      FN: Illustrate combined PAGING/FSC126 utilities
[2]   ⍝ RC - Numeric vector        0 if ok, 1 if error in execution.
[3]   ⍝ Initialise return code, assume all ok
[4]    RC←0
[5]   ⍝ Set up current panel name
[6]    PANEL←'MY∆PANEL'
[7]   ⍝ Create/Select page (Note: GDDM must already be initialised)
[8]    →(er,di,rd)IF 0 1 2 =CSPAGE PANEL
[9]   ⍝ Now use the FSC126 utilities as normal
[10]  di:DISPLAY PANEL
[11]  ⍝ Show screen and wait for ENTER or PF Key
[12]  rd:INT←SREA
[13]  ⍝ ...
[14]  ⍝ More processing ...... (SWRI, SGET, exit on PF 3 etc)
[15]  ⍝ ...
[16]  ⍝ Reselect the page in case we changed to another panel
[17]   →(er,di,rd)IF 0 1 2 =CSPAGE PANEL
[18]  ⍝ Re-read the screen
[19]   →rd
[20]  er:⎕←'Failed to display panel ',PANEL
[21]   RC←1
    ∇