SCREEN HANDLING ROUTINES (SCREEN) CHAPTER 1 RSX-11M SUBROUTINE SPECIFICATION Screen Handling Routines (SCREEN) Contents 1. Introduction 2. Subroutine Structure 3. General Calling Sequence 4. Subroutines and Parameters Appendices A. Subroutine Summary B. Error Returns C. Assembly and Task Building D. Future Improvements Planned E. An Alternative Method for SYSTIME VDUs. SCREEN HANDLING ROUTINES (SCREEN) PAGE 2 CHAPTER 1 1. INTRODUCTION SCREEN represents a set of subroutines which allow the user fully to utilise the capabilities of his V.D.U. Not only does it incorporate the standard facilities of cursor-positioning, screen clearing and so on (which most VDUs support) but also the special facilities such as double-height characters, second font and so on that are available on only a few terminals (such as the SYS- TIME MK3). SCREEN provides an interface to these facilities that is: (i) Easy-to-Use (No need to remember complicated es- cape sequences). (ii) Terminal Independent (The same program source may be used for different terminal types - the only difference is in the task-building stage). (iii) Language Independent (The subroutines support all the standard languages available on RSX-11M - MACRO-11, FORTRAN, COBOL AND BASIC-PLUS-2). SCREEN HANDLING ROUTINES (SCREEN) PAGE 3 CHAPTER 2 2. SUBROUTINE STRUCTURE In any task using them the SCREEN subroutines fall into 3 distinct categories (4 for COBOL) as follows:- 2.1 Terminal Characteristics Table (xxxTBL) Each terminal type has its own characteristics table (see AppendiX C). This is a subroutine consisting pure- ly of data defining the capabilities of the terminal and how to use them in a format that can easily be read by the control subroutine. For each terminal type this module also defines which subroutines are legal by defining the equivalent opera- tor code (FD.XXX) or not. 2.2 Control Subroutine (CTLOUT) This subroutine does all the real work. It is called by the specific subroutines with the required operator code value in one of the registers. It checks that the given code is valid for the current operator type and con- structs the required control sequence in the output buffer with reference to the Terminal Characteristics Table. If so required it then outputs the required characters on the given LUN (See Chapter 3). 2.3 Specific Screen Subroutines (CURPOS, etc.) These are the routines which translate the user's re- quirements into operator codes for the Control Subrou- tine. There is one subroutine for each facility, and each subroutine merely sets the relevant operator code and calls the Control Subroutine to execute it. 2.4 (COBOL only) Common Area Setup Routines The Control subroutine communicates with the user task by means of a COMMON area (.PSECT) which holds the rele- vant information (e.g. Row Number and Column Number for cursor positioning). Unfortunately, COBOL cannot currently map to such a COMMON area, so for COBOL tasks the information has to be set up in the COMMON region by means of specific subroutines (see Chapter 4). SCREEN HANDLING ROUTINES (SCREEN) PAGE 4 CHAPTER 3 3. GENERAL CALLING SEQUENCE As indicated in Chapter 2, communication with the SCREEN subroutines is done by means of a COMMON area, which contains 9 words, as follows:- ADDBUF - Address of buffer to hold control characters. TOTBYT - Length of buffer to hold control characters (in bytes). BYTCNT - Number of bytes in buffer currently used. COLNO - Column Number for Cursor Positioning. ROWNO - Line Number for Cursor Positioning. TABCNT - Tab Count for Tabbing. LINENO - Line Number for setting Scroll Base. OUT - Flag to control whether the Control Subroutine outputs the sequence or not (1 = Yes). LUN - Logical Unit Number for Output if OUT = 1. These are words rather than bytes because some languages do not support bytes. The common area definition, suitable for inclusion in a user program, is given in the files. SCREEN.MAC (for MACRO-11) SCREEN.FTN (for FORTRAN) SCREEN.B2S (FOR BASIC-PLUS-2) As explained before, COBOL does not support this struc- ture, and the subroutines described in Chapter 4.2 must be used. However, a file is supplied defining the vari- ables needed in COBOL, SCREEN.LIB Each of these files also contains a buffer (40 bytes long) suitable for use by the Screen Subroutines. This may be changed by the user, but should not be less than 20 bytes long (which will cover all single control se- quences). Before any SCREEN routines can be called, the fields ADDBUF, TOTBYT and BYTCNT must be initialised. If we suppose that the user is using the default buffer BUFF, then to set up ADDBUF he should do one of the SCREEN HANDLING ROUTINES (SCREEN) PAGE 5 CHAPTER 3 following:- MACRO - MOV #BUFF,ADDBUF FORTRAN - CALL GETADR (ADDBUF, BUFF) BASIC-PLUS-2 - CALL GETADR BY REF (ADDBUF%, BUFF$) COBOL - CALL "SETBUF" USING BUFF,TOTBYT. (See Chapter 4.2) TOTBYT and BYTCNT can be set up in the normal way (ex- cept for COBOL). If the Control Subroutine is to do the output, then OUT and LUN should also be set up. The standard LUNs used by the languages are:- MACRO - LUN 5 defaults to TI: FORTRAN - The TYPE command uses LUN 5 BASIC-PLUS-2 - The PRINT command uses LUN 13 COBOL - The DISPLAY command uses LUN 1. These defaults are set up for the first 3 languages, but for COBOL a CALL "SETLUN" should be performed to set the default (although a call to "SETBUF" also sets the default). In FORTRAN or MACRO-11 other LUNs can be used if re- quired just by altering the value of LUN, but the user is advised against using other LUNs for BASIC-PLUS-2 or COBOL where the LUN/device correlation is less obvious. The OUT flag should also be set to 1 if the Control Su- broutine is to do the output. For COBOL this is done by doing a CALL "SETOUT" (although a call to "SETBUF" also sets OUT to 1) Usually for high-level languages it is more convenient for the output to be done by the Control Subroutine than by the task. Having set up the initial conditions, the subroutines may now be invoked simply by SCREEN HANDLING ROUTINES (SCREEN) PAGE 6 CHAPTER 3 CALL INVON - MACRO, FORTRAN OR BASIC-PLUS-2 or CALL "INVON". - COBOL The three subroutines CURPOS, SCRBAS and TAB (q.v.) re- quire values to be set up in the Common Area. Variations of these exist as CURPS1, SCRBS1 and TAB1 where the parameters are supplied in the subroutine call. These are mainly for use in COBOL programs but may be used from the other languages as well if so de- sired. In the specific subroutine descriptions that follow, each subroutine name is accompanied by its operator code descriptor (FD.XXX). This is because if you use a su- broutine such as CLSCNR - Clear Screen(Rest) on a terminal which does not support the facility (e.g. SYSTIME MK2), then the Task Builder will report an 'undefined symbol' of FD.CSR which is the corresponding operator code descriptor. Note that care must be exercised when using standard language statements to output text at a given cursor po- sition, as the statements often have implied carriage-control. In MACRO-11 specify a Carriage-Control (3rd param in IO.WLB) of 0. In FORTRAN specify both '+' and $ in the FORMAT State- ment (e.g. ('+',$,'TEXT')). In COBOL ensure that there was a DISPLAY...WITH NO AD- VANCING before the relevant output. In BASIC-PLUS-2 append a semi-colon to the PRINT state- ment (e.g. PRINT A$;). Examples of the language are given in TEST.MAC, TEST.B2S, TEST.FTN or TEST.CBL. SCREEN HANDLING ROUTINES (SCREEN) PAGE 7 CHAPTER 4. 4. SUBROUTINES AND PARAMETERS 4.1 General Subroutines (i) RESET (FD.RST) Resets the terminal to its initial state (i.e. state after being switched on). (ii) TAB (FD.TAB) Moves the cursor on the current line to the column number specified in TABNO. Columns are numbered starting at 1 (the left-hand margin). The alternate entry point for this request is TAB1 (TABNO) where the tab number is passed as a parameter. The second entry point must be used for COBOL. (iii) CURPOS (FD.POS) Moves the cursor to the position specified by COLNO and ROWNO for line number and column number respectively. Columns are numbered starting from 1 for the left-hand margin. Lines are numbered starting from 1 for the top of the screen. -1 may be specified in either ROWNO or COLNO to represent the bottom line of the screen or the right-hand column respectively. If either value is outside the limits of the dev- ice, the request is ignored. The alternative entry point for this request is CURPS1 (ROWNO,COLNO) where the line and column numbers are passed as parameters. The second entry point must be used for COBOL. (iv) NEWLIN (FD.NLN) Advance the cursor to the beginning of the next SCREEN HANDLING ROUTINES (SCREEN) PAGE 8 CHAPTER 4. line. (v) BELL (FD.BEL) Ring the bell on the terminal. (vi) DISCTL (FD.CTL) Disable control characters on the terminal. This means that keys depressed with the CTRL key also depressed will be ignored. (vii) ENACTL (FD.DET) Re-enable control characters. (viii) CLLINA (FD.CLA) Clear the whole of the current line from column 1 to the end. (ix) CLLINR (FD.CLR) Clear the rest of the current line from the cur- rent cursor position. (x) CLSCNA (FD.CSA) Clear the whole of the screen from the home posi- tion (1,1) to the end. Note that on most termi- nals the cursor is left at the Home position. (xi) CLSCNR (FD.CSR) Clear the rest of the screen from the current cur- sor position to the end. (xii) HOME (FD.HOM) Move the cursor to the Home position (Line 1 Co- lumn 1). (xiii) INVON (FD.ION) Set the screen into Inverse Video mode. Note that the effect of this varies from terminal to termi- nal. On some terminals (e.g. SYSTIME MK3) this just sets an Inverse On flag so that all char- acters displayed subsequently at the terminal are displayed in Inverse Video until the switch is turned off. On other terminals (e.g. SYSTIME MK2) this results in an actual character being output on the screen and all characters on that SCREEN HANDLING ROUTINES (SCREEN) PAGE 9 CHAPTER 4. line to the right of it will appear in inverse video (whether these already are displayed later) up to any Inverse off character on that line. Characters on other lines are not affected at all. (xiv) INVOFF (FD.IOF) Switch off the Inverse Video mode. See (xiii). (xv) LED1ON (FD.LT1) Switch on the lst LED on the terminal. (xvi) LED2ON (FD.LT2) Switch on the 2nd LED on the terminal. (xvii) LED3ON (FD.LT3) Switch on the 3rd LED on the terminal. (xviii) LED4ON (FD.LT4) Switch on the 4th LED on the terminal. (xix) LEDOFF (FD.LOF) Switch off all the LEDs on the terminal. (xx) PAGMOD (FD.PON) Set the terminal into Page Mode - i.e. a CR/LF on the bottom line will position the cursor to the Home Position without scrolling. (xxi) SCRMOD (FD.POF) Set the terminal into Scroll Mode - i.e. a CR/LF on the bottom line will cause the whole page to scroll up a line. (xxii) BLNKON (FD.BON) Set the terminal into Blinking On Mode. (xxiii) BLNKOF (FD.BOF) Set the terminal into Blinking Off Mode. (xxiv) UNDRON (FD.UON) Set the terminal into Underscore On Mode. SCREEN HANDLING ROUTINES (SCREEN) PAGE 10 CHAPTER 4. (xxv) UNDROF (FD.UOF) Set the terminal into Underscore Off Mode. (xxvi) CURSR1 (FD.CT1) Set the cursor to be a Static Block. (xxvii) CURSR2 (FD.CT2) Set the cursor to be a Flashing Block. (xxviii) CURSR3 (FD.CT3) Set the cursor to be a Static Underline. (xxix) CURSR4 (FD.CT4) Set the cursor to be a Flashing Underline. (xxx) FONT1 (FD.FT1) Set the terminal to use Character Font 1. (xxxi) FONT2 (FD.FT2) Set the terminal to use Character Font 2. (xxxii) FULINT (FD.FUL) Set the terminal into Full Intersity Characters. (xxxiii) HLFINT (FD.HLF) Set the terminal into Half Intersity Characters. (xxxvi) PAGE 1 (FD.VP1) Direct all future output to VDU Page 1. (xxxv) PAGE 2 (FD.VP2) Direct all future output to VDU Page 2. (xxxvi) PRNTER (FD.PRT) Direct all future output to the Slave Printer. (xxxvii) DMPSCR (FD.DMP) Dump the contents of the screen onto the Slave Printer. SCREEN HANDLING ROUTINES (SCREEN) PAGE 11 CHAPTER 4. (xxxviii) DISP0 (FD.DP0) Hide both VDU Pages. (xxxix) DISP1 (FD.DP1) Display VDU Page 1 but Hide VDU Page 2. (xxxx) DISP2 (FD.DP2) Hide VDU Page 1 but Display VDU Page 2. (xxxxi) DISP12 (FD.DP3) Display both VDU Pages. (xxxxii) STRCUR (FD.STR) Store the current cursor position. (xxxxiii) RSTCUR (FD.RES) Restore the cursor to its stored position. (xxxxiv) SNGWID (FD.SWD) Output characters as Single Width. (xxxxv) DUBWID (FD.DWD) Output characters as Double Width. Note that some terminals only allow Double Width characters that are double Height as well. (xxxxvi) SNGHGT (FD.SHT) Output Characters as Single Height. (xxxxvii) DUBHGT (FD.DHT) Output Characters as Double Height. Note that some terminals only allow Double Height characters that are Double Width as well. Also some termi- nals regard the Double Height characteristic as: (a) Line Specific or (b) Divided into Double Height Upper and Double Height Lower. If in doubt consult your terminal Technical Spec- ification. (xxxxviii) SCRBAS (FD.BAS) SCREEN HANDLING ROUTINES (SCREEN) PAGE 12 CHAPTER 4. Set the terminal's scroll base to the line defined by LINENO. If the line number is out of range for the terminal the request is ignored. Note that various terminals implement Scroll Bases in dif- ferent manners (the SYSTIME MK3, for instance, has 2 different specifiable Scroll Bases). The alternative entry point for this request is SCRBS1 (LINENO) where the line number is passed as a parameter. The second entry point must be used for COBOL. 4.2 COBOL - Specific Subroutines (i) SETBUF (BUFF, TOTBYT) This routine stores the address of the buffer BUFF in ADDBUF in the COMMON area and the contents of TOTBYT (which should be the length of BUFF in bytes) in TOTBYT in the COMMON area. It also sets BYTCNT in the COMMON area to 0 OUT " " " " " 1 LUN " " " " " 1 (ii) SETLUN (LUN) This routine stores the contents of LUN in the variable LUN in the COMMON area. If the parameter is omitted a value of 1 is assumed. (iii) SETOUT (OUT) This routine stores the contents of OUT in the variable OUT in the COMMON area. If OUT is -1 then the current contents of the buffer are output to the terminal and OUT is reset to 0. If the parameter is omitted a value of 1 is as- sumed. (iv) GETCNT (BYTCNT) This routine returns the current value of BYTCNT in the COMMON area into the variable BYTCNT. If the parameter is omitted the request is ignored. SCREEN HANDLING ROUTINES (SCREEN) PAGE 13 APPENDIX A APPENDICES A. SUBROUTINE SUMMARY RESET Reset terminal TAB Move cursor to given column CURPOS Position cursor at given line/column NEWLIN Move cursor to start of next line BELL Ring the terminal bell DISCTL Disable control characters ENACTL Enable control characters CLLINA Clear the whole line CLLINR Clear the rest of the line CLSCNA Clear the whole screen CLSCNR Clear the rest of the screen HOME Move the cursor to HOME INVON Switch Inverse Video On INVOFF " " " Off LED1ON Switch LED1 On LED2ON " " 2 " LED3ON " " 3 " LED4ON " " 4 " LEDOFF " all LEDs off PAGMOD Put terminal into Page Mode SCRMOD " " " Scroll Mode BLNKON Set Blinking On BLNKOF " " Off UNDRON " Underlining On UNDROF " " Off SCREEN HANDLING ROUTINES (SCREEN) PAGE 14 APPENDIX A CURSR1 Set cursor to Static Block CURSR2 Set cursor to Flashing Block CURSR3 Set cursor to Static Underline CURSR4 Set cursor to Flashing Underline FONT1 Set terminal into character Font 1 FONT2 " " " " " 2 FULINT Set characters to be Full Intensity HLFINT " " " " Half Intensity PAGE 1 Direct Output to VDU Page 1 PAGE 2 " " " " " 2 PRNTER " " " Slave Printer DMPSCR Dump screen contents to Slave Printer DISP0 Hide both VDU Pages DISP1 Display VDU Page 1 only DISP2 " " " 2 " DISP12 " both VDU Pages STRCUR Save current cursor position RSTCUR Restore saved cursor position SNGWID Set characters to be Single Width DUBWID " " " " Double " SNGHGT " " " " Single Height DUBHGT " " " " Double " SCRBAS Set Scroll Base SETBUF Set Buffer address and length (COBOL only) SETLUN Set Logical Unit Number (COBOL only) SETOUT Set Output Flag (COBOL only) GETCNT Get Current Byte Count (COBOL only) SCREEN HANDLING ROUTINES (SCREEN) PAGE 15 APPENDIX A B ERROR RETURNS Errors are returned in R0. The possible values are:- 0 = Success 1 = Feature not Supported -1 = Insufficient Room in Buffer As High-Level languages cannot usually access R0, the value of BYTCNT is also negated if there is Insufficient Room in the Buffer. If there is any chance of this hap- pening, it must be checked for. SCREEN HANDLING ROUTINES (SCREEN) PAGE 16 APPENDIX C C. ASSEMBLY AND TASK-BUILDING Each subroutine is merely assembled with a line similar to MAC CURPOS = CURPOS and included in the library SCREEN.OLB. As the XXXTBL modules all contain the same global variables, they must be included in the library with the /-EP switch. To build a task using the subroutines, a line should be used similar to TKB TEST = TEST,[1,1]SCREEN/LB:XXXTBL,SCREEN/LB, (any language - specific libraries) where XXX defines the terminal type to be used. There are currently 8 terminal types, as follows:- (i) L36 Any hard-copy device (e.g. LA36) Supports function (ii),(iii)[as CR/LF],(iv) and (v) (ii) MK2 The SYSTIME MK1 or MK2 terminals (or MK3 in compatibili- ty mode) Supports functions (i) - (v), (viii), (ix), (x), (xii) - (xxi). (iii) MK3 The SYSTIME MK3 terminal Supports all functions. (iv) V52 The VT52 terminal (or VT100 in compatibility mode) Supports functions (i) - (v), (viii) - (xii) (v) V5H The VT50H terminal Supports functions (i) - (v), (viii) - (xii) (vi) V50 The VT50 terminal Supports functions (i), (ii), (iv), (v), (viii) - (xii) (vii) VTC SCREEN HANDLING ROUTINES (SCREEN) PAGE 17 APPENDIX C The VT100 terminal Supports functions (i) - (v), (viii) - (xiv) (viii) H15 The Hazeltine 1500 or 2000 terminals Supports functions (ii) - (v), (viii) - (xii) Note that as explained previously, any attempt to refer- ence a function which is not supported by the terminal type will produce undefined symbol error in the Task-Builder for the corresponding Operator Code des- criptor. The program can still be used, but the Control Subroutine will just ignore the requests it cannot han- dle. SCREEN HANDLING ROUTINES (SCREEN) PAGE 18 APPENDIX D D. FUTURE IMPROVEMENTS PLANNED (i) Extend VT52 and VT100 support. (ii) Provide interface to Graphics capability of terminals. (iii) Handle RSX's insertion of CR/LF after 80 characters. SCREEN HANDLING ROUTINES (SCREEN) PAGE 19 APPENDIX E E. AN ALTERNATIVE METHOD FOR SYSTIME VDUs Programs wishing only to perform (i) Cursor Positioning (ii) Screen Erases (iii) Line Erases on Systime terminals may use an alternative approach. In this the user outputs the actual cursor positioning characters at the front of his display string. To do this the programmer uses a combination of the fol- lowing variables:- ATT - Prefix String for Cursor Positioning COL - 80-element array defining the column to be used LIN - 24-element array defining the line to be used ERASE - String to Home Cursor and Erase Whole Screen NULL - String required to follow ERASE on Systime MKI/II terminals ERALIN - String to Erase from current cursor position to end of line (Note that in BASIC-PLUS-2 each variable name is suf- fixed with a $). The definitions of ATT,COL,LIN,ERASE and ERALIN are held in the files CURSOR.MAC (MACRO-11) CURSOR.FTN (FORTRAN) CURSOR.B2S (BASIC-PLUS-2) CURSOR.LIB (COBOL) If writing in FORTRAN or MACRO-11,note that ATT and ERASE are 2 bytes long each, and ERALIN and each element of COL and LIN are one byte long. These variables are used as follows:- (i) To Position Cursor to Column 10 on Line 5 and output the text "HELLO" from a COBOL SCREEN HANDLING ROUTINES (SCREEN) PAGE 20 APPENDIX E Program:- DISPLAY ATT,COL(10),LIN(5),"HELLO" (ii) To Clear the Screen from a FORTRAN program (assumed on a MKII VDU):- TYPE 100,ERASE,NULL 100 FORMAT (2A2) (iii) To Position Cursor to Column 10 on Line 5, output "FILENAME >" and Clear the rest of the line, from a BASIC-PLUS-2 Program:- PRINT ATT$;COL$(10%);LIN$(5%);'FILENAME >'; ERALIN$; and so on. The sample programs supplied (TEST.MAC etc.) use a mix- ture of the two methods for demonstration purposes.