Screen Management System Subroutines Ken Messer Allied Electronics 401 East 8th Street Fort Worth, Texas 76102 This submission consists of a group of subroutines written in VAX BASIC V2.3, comprising a system allowing the (relatively) simple usage of the new VAX Screen Management System under VMS version 4.2. Also included is a demonstration program using it. With this system, a programmer can create up to 10 virtual displays and manipulate them quite simply, by keeping track of the sequence number of the intended virtual display (1 through 10) and passing that number as an argument in the subroutine call. Specific information about the routines, as well as argument layouts and more detailed explanations, are to be found in SMGDOC.MEM, which is included in the submission. The submission includes a library containing compiled object code, as well as the source code for the included routines. This makes it possible for any shop to use these routines, either by setting the library up as a system link library or including it in the linker command line. One of the main design criteria was to allow simple conversion from Allied's current screen system, which consists of a library of special purpose screen display and input routines for DEC and foreign terminals. These routines take input from the terminal and present it to the program as it was entered (with the exception of the function keys). Validation of input is thus left to the calling routine, with all input is returned to it as character data. (It would be easy enough to call these routines from within the context of a validation routine, however.) The input of a function key is passed to the calling routine as its name, preceded and followed by circumflexes ("~PF1~", "~F17~", and "~KP6~", for example). All data to be displayed on the screen must be sent via routines in this system, or using DEC SMG Library functions. PRINT statements and non-SMG routines are not compatible with SMG screen routines and will not work. It is strongly suggested that the applications programmer read the chapter on SMG in the Run-time Library Manual (Volume 5C in the VMS 4.x doc set) to Screen Management System Subroutines Page 2 gain some understanding of what the routines do, as well as what they cannot do. (For one thing, SMG gets very disturbed if you try to get input at a point on a virtual display that is occluded by another virtual display.) Another thing to keep in mind is that this system was designed to control the creation and deletion of virtual displays, and using SMG library routines to do this instead of SMG_Add_Virtual_Display and SMG_Delete_Last_Virtual_Display is emphatically NOT supported. A few hints about the system: o If you will be working with the source code of these routines, it will be necessary to define the logical (SMG$LIBRARY) pointing to the location of SMG.DFN. This is the common area used by the routines to do all the interfacing with the DEC SMG routines. o If you have a BASIC compiler and find the need to use more than ten virtual displays, you need to make a few changes: the subscripts (in SMG.DFN) of the following variables need to be increased to whatever number of virtual displays are required: Display_ID() Display_Rows() Display_Cols() (Following any changes to the COMMON area it is, of course, necessary to recompile all routines and re-insert them into the SMG library, prior to relinking any routines that use this system.) Since SMG_Add_Virtual_Display currently will not allow more than ten displays to be created, it is also necessary to change this routine as well. o To reduce the possibility of errors brought on by wrong data types, those with BASIC compilers would do well to place this statement in the data declarations section of each routine calling an SMG subroutine: %INCLUDE SMG$LIBRARY:SMGDECLARE.INC This will ensure that literals and undeclared variables passed as arguments will be converted to the proper data type, if possible, generating a compiler warning along the way. When the routine asks for a LONGword argument, it really wants just that. Of course, SMG$LIBRARY will need to be defined, or another suitable logical used. Screen Management System Subroutines Page 3 o Each program must have a call to SMG_OPEN before any other of these routines is called. Likewise, strange things could happen to the setup of a terminal if SMG_CLOSE is not called before exiting a program. o If the gurus at DEC make changes in $SMGDEF in some future release (after 4.2) (which is highly likely for such a new system), or if you wish to create or recreate the object library for this system, you will need to: 1. Extract $SMGDEF.MAR from SYS$LIBRARY:STARLET.MLB 2. Edit the file to add these lines: .TITLE SMGDEF ; At the top after the .MACRO line $SMGDEF GLOBAL ; At the bottom after all other lines .END 3. Compile the module 4. Insert it into SMGLIB.OLB (or whatever) A demonstration program, IMAGES, has been included with the submission. It is (yet another!) SYSTAT type display, making use of the SMG routines to print a system status table on the screen. The screen is updated (by default) every 30 seconds, using display batching. By setting IMAGES up to run with a foreign command, the screen update time can be changed from the default with a switch (/15 for fifteen seconds, for example). Other functions of the program are documented on the screen at startup. This system is still being refined at Allied, and has been reasonably well debugged. It has been in use in several production programs for about 6 weeks with great success. We would appreciate hearing about bugs discovered and suggested enhancements to the system (through the mail, please!).