Full-screen Methods with APL2

VECTOR Vol.7 No.4

Full Screen Methods with APL2

by Peter Branson

Introduction This is mostly concerned with APL2 on the mainframe and, although there is a widespread tendency to move APL applications down to PC’s or the RS 6000, ete., there is still plenty of mainframe code out there. In most cases, APL mainframe systems are likely to have been around a while, and the full screen techniques well established, possibly with a set house-style. Nevertheless, mainframe APL development does still go on, and a review of some of the full screen methods available may be of interest to relative newcomers.

My primary interest is alphamerics for menus, reports, tables, etc. but graphics will get some mention. I will cover four approaches: (1) Character Matrix, (2) GDDM (AP126), (3) ISPF and (4) AP124 (yes, AP124!). As always, everything is in origin-1. ] use TSO, but most of what I have to say also applies to VM.

Character Matrix For simple menu systems, this is the oldest, the easiest and the cheapest method. Obviously, all you need to do is clear the screen (AP100 and TSO CLEAR), construct and display the matrix, have a little prompt/ response function and use OPc(2]. By the way, APL2 provides a rather neat way for that prompt function:

vVIPX(Oiv Col Z+IPX MSG;0PR C1] a APL2 prompt/response fn C2] OPR+' [3] f+mse (4) 0 Zege")

Z+QWGET 1

(This won't work on APL2/PC since DPR is not yet implemented)

I can anticipate screams of horror at the thought that a professional  APL-er might still do full screens this way, but it does actually work! Of course, a prime objection is that it is too easy to interrupt back to raw APL, so there are many systems where you should NEVER use it. In some of our systems, though, for

126

VECTOR Vol.7 No.4

historical reasons we still have menus created this way, and with several hundred users over many years J am not aware of many complaints. I think the essential point is that our users are relatively sophisticated and would not be put off by accidentally hitting a wrong key. Of course, you shouldn’t nest these simple menus too deeply since this makes backing out frustrating.

Graphical Data Display Manager I suppose that GDDM (assessed via AP126) is regarded as the main IBM tool for full screen work, both text and graphics. However, it is expensive, and buffering of the GDDM calls where possible should be used to minimise CPU time. There is a good paper by Dick Bowman on how to set about this (Bo89).

As Dick points out, the APL2-supplied GDMX function (in workspace 2 GDMx) has very complex internal logic and seems to be designed on the basis that it will still work and access any new GDDM calls that IBM might invent in the future. However, I live in the here and now, and Dick’s simpler type of code is far preferable. For serious full screen work a design tool is essential. Many sites will still have [BM’s 2 FSDESIGN which does this, but this is obsolescent; in any case it does not support buffered GDDM calls. Dick Bowman’s paper, though, does give the bones of an alternative design tool which works quite well. Be warned however! If you start copying his code, by the time you have nearly finished you come across that most helpful of all APL lines:

FIELDPOS(26] etc, etc, etc.

Yes, you need about another 60 lines here, so you will have to understand the code after all - which is always a good idea anyway!

FIELDFOS does all the work to add, delete, move, resize, etc. screen fields and uses a couple of unexplained functions (VOTOVER and PMAP) which are not listed. Their purpose, though, is pretty clear if you remember that you cannot overlap screen fields in GDDM. The way FIELDPOS works is to generate the new format row and column details each time a change is made and put these with PFMT which holds the parameters for the fields already set. PMAP starts with a screen-size map  of 0’s and goes round PFMT adding a 1in each position  of each field. If we end up with only 0’s and 1’s it’s O.K., otherwise an overlap so throw it away and start again. This is a much simpler method than trying to detect entry errors and putting up messages, ete. and the user soon learns to be careful with cursor positioning.

127

VECTOR Vol.7 No.4

For what it’s worth, my origin-1 code for those functions (combined together) is given at the end. (I wonder if anyone will complain about that loop?), Finally, before leaving FIELDPOS, there is a nice little idiom there for turning a vector 1-column matrix, which I don’t remember seeing before:-

» CxO] VECTOR ++ ({(p VECTOR) ,1)pVECTOR

Interactive System Productivity Facility Or ISPF for short. Many people routinely use this without realising that it is a full screen design system and that you it with APL2. Useful documentation is, however, scattered about.

The APL2 manual (IBM1 pp 72, 73) is not very helpful, although it does tell you how to use the ISPF editor to edit APL2 functions. For long functions (and, yes, they are sometimes necessary, viz. FIELDPOS) this is much better than JEDITOR 2 because of its powerful insert, move, copy, delete etc. facilities for both single lines and blocks of lines. Worth looking at even if you don’t use ISPF for panels. Minor restrictions: (1) You can’t ring-edit - a pity! (2) You cannot have function lines longer than around 230 characters - but who wants to, anyway?

Where next then? You will need up-to-date ISPF manuals (IBM2), (IBM3) and there is a reasonable amount of APL2 there, including some example on which later). You can learn how to write ISPF panels from these sources (and it is not difficult) but it is still not easy to see how to set up a reliable APL2-ISPF bond.

The best starting reference that I have come across is the paper by Loren Mayhew (Ma86) which gives a very clear and detailed account (with code) of one method of proceeding, including the sort of logic needed to incorporate ISPF split-screen mode. (You must not to be called twice! It has, as they say, unpredictable results’!) The key to the success of this method is the use of an AP101 stack to do a )RESET and then re-call the original (QLX) calling function.

One small point; the full-stops (periods) don’t always show clearly in the code as printed and there are names like , HELP’, which is not the same as HELP . Look for suspicious indentations if in doubt. All in recommend this paper as a good place to start.

One thing the above paper doesn’t touch on is ISPF tables, but (IBM3) is quite good here and has a worked telephone book example with two APL2 functions

128

VECTOR Vol.7 No.4

TELEBK and TELESY. This code can be tidied up somewhat but it is worth coding up to learn about ISPF tables. One thing to be aware of is that it is not fully robust. If, for example, you try from the panel to delete a report before you have created it, you will have a nasty ABEND. There are a few like this, all sequence dependent, but they are easily covered by initialising some flags in TELEBK and trapping/switching them in TELESV to enforce correct sequencing.

The telephone book and (Ma86) between them cover almost everything you need to know about APL2 with ISPF. One exception is perhaps dynamic table building, a useful technique for large tables. (IBM2) has a selection on this with a worked PL/1 example. Even if you don’t know PL/1 this is easy to translate into APL and gives a good insight, including how to use the excellent supplied scrolling facilities e.g. PF7, PF8. Also things like DOWN 500 or M for MAX on the command line, then PF8 to jump straight to the bottom of the scrolled data, etc.

With a properly set up ISPF system, there is no need to back out of menus; you can jump from almost anywhere to almost anywhere else. For example, =3.4  will go straight to option 3.4, and =X  will get you home wherever you are. Tf you want to do this sort of thing yourself, perhaps using GDDM, the logic is not exactly trivial and with ISPF it is already done for your.

Amongst the things I like about ISPF is the excellent help tutorial; you may need to write some application-specific help panels, but all the stuff about scroll commands, etc. is already there. Another thing is toggling the PF key display. A beginner can type PFSHOW ON on the command line to get them displayed and, when they are familiar, the PFSHOW OFF will get rid of them. Apart from the default PF key settings, application-specific ones can readily be set dynamically.

One piece of advice is to never waste time typing complete ISPF panel; instead, copy one of your own, or someone else’s, and change it. For example, for your first primary  panel, pick the ISPF primary panel itself and modify a copy of that. If you see a panel you like somewhere just type PANELID on the command line to get its member name, then go look in the SYS...ISPPLIB libraries, or wherever, to grab a copy.

Someone mentioned to me a while back that a possible problem with ISPF-APL2 was competition for attention interrupts. Our relations with our end users are such that we can simply tell them not the use the attention key and they meekly obey. However, if this matters to you, I think it can be handled with an attention exit routine’ calling CLIST; this is discussed in (IBM2) but I have not tried it yet.

129

VECTOR Vol.7 No.4

I like ISPF panels. The APL code is a little messy because everything (even numbers) has to be passed character string, but the panels are easy to set up (almost WYSIWYG) and a whole raft of excellent data comes ready-supplied.

ISPF is also available on the PC, I gather, but I have not tried it because you cannot link it to APL2/PC. IBM tell me that I am the first person to request this option, and T hope that they can find time to build it in.

AP124 This was IBM’s precursor to AP126 and allowed full-screen panels without the GDDM overhead. Well, IBM don’t supply this any more, so why bother to mention it? Firstly, old VSAPL systems converting to APL2 (if there are any left who haven't done so already) either have to rewrite the full screen work or simulate this, perhaps even using GDDM (Yuk!). Fortunately I don’t have this problem. What I am more interested in are commercial packages like FSM124 from Interprocess Systems which simulates AP124 without using GDDM, and is reportedly cheaper to use. I am hoping to test run this in the not too distant future.

Coming down from the mainframe for a moment, I am also interested in APL2/PC which doesn’t have AP126 but does have AP124 so I am also getting involved there. The supplied workspace for AP124 (called AP124) does have a modest full-screen design function, FSDEF, but this requires all the individual field parameters to be hard-coded inside application functions, which is not very satisfactory for serious design work. Also, the code has been brought down from VSAPL and is distinctly APL1, with a plethora of global variables, etc.

If you want an AP124 full-screen design kit, which itself exploits the full-screen capabilities, then it’s (almost) all there in Adrian Smith’s book (Sm82), if you can beg, steal or borrow a copy. You will need some modifications for the PC (see the IBM PC manual) and, interestingly, you can now use overlapping fields for things like adding a uniform background colour. Finally, you will need to get rid of the embedded [JA¥ code, and (I'm sure Adrian would agree now that APL2 is available) might nowadays prefer using a nested array to avoid those global names.

Alternatively, if you prefer Dick Bowman’s GDDM approach, it is difficult to modify this for AP124.

130

VECTOR Vol.7 No.4

Graphics Of the above four methods, only GDDM will do graphics on the mainframe, but as one keeps repeating, it is expensive. If you need mixed text and graphics GDDM can do this but, if your work is mostly text with a small graphics content, consider using ISPF and calling GDDM from there, which is possible with the latest release of ISPF.

I think, though, that these days many people would recommend downloading the data to a PC and using one of the excellent PC graphics packages like Harvard Business Graphics or Lotus Freelance, etc. This is the approach that we now use.

Is GDDM obsolescent?

References [Bo89]_ Bowman, R. APL and GDDM - A High Performance Toolkit’ APL89 Conference Proceedings pp 43-53

[Ma86] Mayhew, L. Increasing Productivity with ISPF/APL2’ APL86 Conference Proceedings pp 243-251

[IBM1] APL2 Programming: System Services Reference’ IBM Publication SH20-9218-2 (Nov 87) [IBM2] ISPF: Dialog Management Guide: MVS" IBM Publication SC34-4112- 00 Jun 87)

[IBM3] ISPF: Dialog Management Services and Examples: MVS’ IBM Publication SC34-4113-00 (Jun 87) [Sm82] Smith, A. APL - A Design Handbook for Commercial Systems’ (1982) - Out of print

131

VECTOR Vol.7 No.4

Appendix

VOVER(OIV fo] C4] C2]

Ca] Cs] [6] C7] [8] C9] [10]

C44] C18] R+TL_NM OVER PFMT;FF3M;I;F;R8;CS a Check for overlapping fields Ben on no on on nnn en er eee nee a aM - 'Bitmap' matrix of screen. M[J;K] is :- a 0 if unused, 1 if OK fld posn, >1 if overla, q--------------------------~--------------+ FF+(G+£2}1402]PFM?),C1]7L_NM a fld M+(SS- 0 1)90 a SS is global screen size I+0 BLP:>((AtpFP)<I+*I+1)/OLAP F*FF(I;] (RS CS)+(~14+F01]+1F 03] ) (W1+P C21 +1 F 64] ) MURS; CS]+1+MERS;CS] a Note addition +LP A~- - OLAP:R+lei<,M a R if overlap, 0 if OK

132