Program ID : SCREENCTL.EXE Written by : Jim McDowall (519)255.3348 Board of Education for the City of Windsor 451 PArk St. W. Box 210 Windsor, Ontario N9A 6K1 Last Revised March 1, 1988 Function : This program is used to perform a range of terminal screen attributes and characteristics functions. Such things as drawing lines, boxes, clearing parts or all of the screen, getting user input, and turning on and off the local echo. Listed on the following pages are the various functions performed by this program. Being an executable module, the time required to perform these functions is far less than the time required by a DCL command procedure that does the same task. ACCESS METHODS The functions performed by the program can be accessed in three ways. 1] Using foreign commands set up as global symbols. 2] Creating an RMS file for the program to read. 3] Job Stream Input. METHOD #1 FOREIGN COMMANDS In order to use this program, using foreign commands, global symbols should be set up using the following command format; $ sym :==$disk:SCREENCTL func Where: sym being the global symbol to be connected to the function. disk " the logical device where the program is located. " the directory where the program is located. func " the function to be performed. Example: $ BOX :==$SYS$COMMON:SCREENCTL BOX This example defines BOX to execute SCREENCTL to perform the box drawing function. To use BOX the following would be found in a command procedure; $ BOX 1 1 80 3 This will draw a box on the screen starting on line 1 column 1 and 80 columns across the screen and be 3 lines deep. The program SCREENCTL.EXE will create all the Global symbols required to execute all the functions listed on the following pages. To do this, all that is required is the Statement; $ MCR disk:SCREENCTL CREATE Where: disk being the logical device where the program is located. " the directory where the program is located. A logical named SCREEN$CTL will be created in the process' JOB logical table which will point to the directory where SCREENCTL is located. The global symbols created will use this logical. Eg. The Symbol BOX will be declared as; $SCREEN$CTL BOX Continue... ACCESS METHODS [2] The following functions are supported by SCREENCTL, but are not created symbols during the create option; CLED, GETCMN, LED, LEDx, PUTCMN. These symbols can be created using the access method #1 described on page one. If a command procedure was used to execute various SCREENCTL functions, each line of the command procedure can have more than one command. These functions must be separated by a back slash "\". Example: $ CLEAR \BIG 1 8 "Windsor Board of Education"\BOX 3 2 77 1 This line will execute three SCREENCTL commands; 1) CLEAR 2) BIG 3) BOX  Notice the space separating the first command and first Back Slash This space is required to ensure proper running of all functions. This is because the back slash can be part of a symbol name.  METHOD #2 FILE INPUT If SCREENCTL.EXE is executed using the DCL RUN command, Eg. $ RUN SCREENCTL. A file named "SCREEN$CTL.INPUT" is searched for in the current default directory. If the file is present, it is used as input for any SCREENCTL commands. When executed using the DCL "MCR" command a user supplied file name can be used in place of the default file name. Eg. $ MCR SCREENCTL SCREEN1.DAT The user supplied file name can be any file name which complies to the VMS file naming structure. The files can contain any number of SCREENCTL commands, but ONLY ONE command per line. METHOD #3 JOB STREAM If SCREENCTL.EXE is executed using the DCL command; $ MCR SCREEN$CTL SYS$INPUT within a command procedure, the program will read the SCREENCTL commands which follow the execute command in the command procedure. Example: $ MCR SCREEN$CTL SYS$INPUT CLEAR BIG 1 8 "Windsor Board of Education" BOX 3 2 77 1 SCROLL 5 24 EXIT $ EXIT  As in method #2, ONLY ONE command per line. Last Statement is EXIT, If exit command is missing and SCREENCTL reads A DCL command, An attempt to execute the DCL command will be made. This Will cause the termination of SCREENCTL. The following pages describe all the functions that SCREENCTL.EXE will perform.  S C R E E N C T L P R O G R A M F U N C T I O N S  Function G e n e r a l D e s c r i p t i o n  BBIG - Same function as BIG but displays characters in BOLD video. BBOX - Draw a box in BOLD video. BEEP - Rings the terminal bell. BIG - Position cursor and display string in large characters. BLACK - Set terminal screen to Light characters dark back ground. BLINK - Position cursor and display string in FLASHING video. BOLD - Position cursor and display string, in BOLD video. BOTTOM - Draw a Horizontal line at the bottom of the screen. BOX - Draw a box. BPOS - Position cursor and display string, and ring terminal bell once. BRIGHT - Turn on BOLD video. BRPOS - Position cursor and display string, in BOLD video. CLEAR - Clear all or part of terminal screen. CLED - Turn off all LEDs on the VT100 keyboard. CURSOR - Move Cursor and Display Text, Turn cursor on and off. ECHO - Turn character echo on. FPOS - Position cursor and display string in FLASHING video. GETAR - Wait for user to press one of the four arrow keys (^,V,>,<) GETFUNC - Wait for user to press any of the VT220 function keys. GETCMN - Recall string data from the process common area. GETPF - Wait for user to press one of the four PF keys. GPOS - Position Cursor and display special graphic character. HLINE - Draw a Horizontal line on the screen. JUSTIFY - Left, Right, or Center Justify text supplied. LED / LEDx - Turn on/off the L1-L4 leds on a VT100 type terminal. LINE - Position cursor on a screen line. Option to clear that line. LPOS - Position cursor on a screen line. Option to clear that line. MORE - Display "Press " on line 24 and wait for user to Press NOECHO - Turn character echo off. PAUSE - Halt procedure execution for given number of seconds. PDINQ - Position cursor, Display string and wait for user input. POS - Position cusor and display string. PUTCMN - Store a string into a process common area. RPOS - Position cusor and display string in REVERSE video. SCRAM - Same as BIG but randomly display characters on line. SCROLL - Set scrolling reagion or JUMP/SMOOTH scroll. SPOS - Position Cursor and display special graphic character. SQUEEZE - Set screen scrolling region and display upper and lower border. TOP - Position cursor in top left position.(HOME). UNBOX - Remove BOX from screen. UNDERLINE - Position cursor and display string in UNDERLINE video. UNSQUEEZE - Cancel SQUEEZE function and set screen to full scroll. VLINE - Draw a vertical line on screen. WHITE - Set terminal screen to light back ground,Dark characters. WINDOW - Draw a box with optional extra Horizontal and vertical lines.   S C R E E N C T L P R O G R A M F U N C T I O N S  Function Parameters Description BBIG See BIG Function. BBOX sl sc w d Starting on line sc column sc, draw box w columns wide and d lines deep. BEEP x Beep terminal x number of times. (10 Max.) Omitting x terminal bell will beep once. BIG l c " " Position cursor on line l column c and display Text in large Characters. l " " Position cursor on line l and display text centered on the line in large characters. /CLEAR Will clear the line before displaying the string. BLACK none BLINK See POS Function. BOLD See POS Function. BOTTOM none BOX sl sc w d Starting on line sl column sc, draw box w columns wide and d lines deep. BPOS See POS Function. BRIGHT none BRPOS See POS Function. CLEAR SCREEN Clear entire screen, put cursor in top left corner. S Clear entire screen, put cursor in top left corner. HOLD Clear entire screen, leave cursor where it is. H Clear entire screen, leave cursor where it is. LINE x Clear line x. L x Clear line x. x y Clear lines x thru y. BOTTOM x Clear screen from line x to the bottom of screen. B x Clear screen from line x to the bottom of screen. TOP x Clear screen from top of screen to line x inclusive. T x Clear screen from top of screen to line x inclusive. Omitting x option for TOP and BOTTOM options will clear the screen from the current cursor line. SCROLL Clear scrolling region of screen only. Cursor is put at top left corner of scroll region. If scroll region is not defined, then entire screen is cleared and cursor is homed. none Clear entire screen, put cursor in top left corner. CLED none Turn off all LEDs on a VT100 type keyboard. CURSOR d p "" Move cursor p number of position on the screen in d direction and display text. OFF Turn cursor off. (NOT ALL TERMINALS). ON Turn cursor on. (NOT ALL TERMINALS).  S C R E E N C T L P R O G R A M F U N C T I O N S  Function Parameters Description ECHO none FPOS See POS Function. GETCMN sy Return a string from the process common area and place it in the local symbol sy. /GLOBAL Makes the symbol "sy" a Global symbol instead of a Local symbol. GETAR l c sy Position cursor on line l at column c and wait for an arrow key to be pressed. Local symbol sy will be set to a value of "U" "D" "R" "L" for arrow key that was pressed. Up, Down, Right, Left. sy Position cursor at start of next line and wait for an an arrow key to be pressed. Local symbol sy will be set to a value of "U" "D" "R" "L" for arrow key that was pressed. Up, Down, Right, Left. GETFUNC See GETAR Return a value of the VT220 function key pressed. See Table 1 after examples page for values returned. This function can also be used in place of the "GETPF" and "GETAR" functions. Will also return value for Keypad keys pressed. See Table 1. GETPF See GETAR Returns a value of "1" "2" "3" "4" for PF key pressed. "PF1" "PF2" "PF3" "PF4". HLINE sl sc l Draw line on line l starting column c for a length of l columns. sl sc nc # Same as above but using optional scan line. Default scan line is 1 (Options 1,3,5,7,9) JUSTIFY l jo "" Position cursor on line l and display characters "" justified using the justify option (jo), Left, right, or center. First letter of the justify word is all that is required for option. Omitting the jo parameter will default to centering the text. A local symbol "LAST_COL" is created by this function to transfer back to the command procedure what column the justified string was started in. LED x Values 1 thru 4 for x will turn on the corresponding led on the VT100 type keyboard. A value of 0 will turn off all LEDs. A value of 5 will turn on all LEDs. LEDx none Symbols LED1, LED2, LED3, LED4 turn on each of the 4 LEDs the same way the LED x option does. LINE See LPOS Function. LPOS l Position cursor on line l of screen column 1. l CLEAR Same as above but also Clear the line. l C Same as above but also Clear the line. MORE none Display "Press to Continue..." on line 24 of screen and wait for the user to press the RETURN key.  S C R E E N C T L P R O G R A M F U N C T I O N S  Function Parameters Description NOECHO none PAUSE x Pause execution of Command procedure or DCL for x seconds. 4.5 is the default if no value for x given. PDINQ l c sy "" Position cursor on line l column c and display Quoted string, and wait for user input. Input will be put into the user supplied local symbol sy. /MARK Option to display a checkerboard at the end of the prompt string. The cursor will be placed on this mark. /SIZE=x Limit the number of characters allowed to be entered. When the limit is reached, input is terminated without requiring the user to press RETURN or ENTER. /GLOBAL Makes the symbol "sy" a Global symbol instead of a Local symbol. /TIME Sets a time limit for a user to respond to the prompt before input is terminated. /TIME=mm:ss allows specific time limit to be set. Default is 10 minutes. If a value is given the form mm:ss must be used regardless of value. /UPPER Request that all input to be Translated to UPPER CASE. /NOECHO Stops the display of characters typed in on the screen. /CLEAR Will clear the line before displaying the prompt.  /MARK, /SIZE, /TIME, /GLOBAL, /UPPER, /CLEAR and /NOECHO options can be placed any where after the first 3 options of "PDINQ" shown above. POS l c " " Position cursor on line l column c and display Quoted string. /CLEAR Clear line l before displaying Quoted string. /DOUBLE Display string D o u b l e S p a c e d on the line. /WIDE Display string in double width characters. /STEP Display string one character at a time across. /Under Display string underlined.  /CLEAR, /WIDE, /STEP, and /DOUBLE options should be placed after the quoted string to be displayed. PUTCMN " " Places the string into the process common area. Up to 250 characters can be placed into the common area. RPOS See POS Function. SCRAM See BIG Function. SCROLL sl el S/J Set scrolling region between line sl and el Optionally set the scroll rate for area on screen. JUMP Set terminal to JUMP scroll. J Set terminal to JUMP scroll. SMOOTH Set terminal to SMOOTH scroll S Set terminal to SMOOTH scroll L S/J Set scrolling region of screen to center L lines of the screen. Optionally set scrolling rate of area. SPOS l c " " Position cursor on line l column c and turn on graphics mode to display character(s) in Quote marks.  S C R E E N C T L P R O G R A M F U N C T I O N S  Function Parameters Description SQUEEZE sl el Same as SCROLL but with top and bottom Borders drawn. sl el x Same as above but with optional border character. (x can be any non numeric character) nl Set bordered scroll area for the center NL lines of the screen. nl x Same as above but with optional border character. (x can be any keyboard character. Default is "=") TOP none UNBOX See BOX Will remove a BOX previously drawn with the BBOX or BOX functions. UNDERLINE See POS UNSQUEEZE none UPOS See POS Function. VLINE sl sc l Draw a Vertical line from line l column c for l number of lines down the screen. WHITE none WINDOW sl sc w d Starting on line sc column sc, draw box w columns wide and d lines deep. h v In addition to the above parameters, a horizontal line can be drawn on line h, and a vertical line can be drawn in column v. To draw a vertical line without drawing a horizontal line, Enter the horizontal line option as 0 (zero). To draw multiple horizontal or vertical line, separate each line with a comma. See examples pages for use of this option. The following pages are some examples of the functions.  S C R E E N C T L P R O G R A M F U N C T I O N S  Examples ========= Using the format on page one, if the previous functions were defined, the following examples will do the following. $ CLEAR LINE 12 - Clear line 12 of the screen. $ CLEAR LINE 2 4 6 - Clear lines 2 4 and 6. $ VLINE 5 30 6 - Draw a vertical line starting at line 5 col. 30 and down the screen for 6 lines. $ HLINE 2 1 80 - Draw a horizontal line on line 2 starting at column 1 across the screen for 80 columns. $ BOX 4 9 47 4 - Draw a box starting on line 4 column 9 across the screen for 47 columns and 4 lines deep. $ BOX 1 1 80 1 22 1 80 1 - Draw two boxes the 1st starting line 1 col. 1 for 80 columns across 1 line deep. The 2nd line 22 column 1 80 columns across the screen 1 line deep. $ BIG 2 5 "NEW" - Position the cursor on line 2 column 5 and print the word NEW in large letters. $ POS 5 11 "''F$LOGICAL("DISK1:")'" - Position the cursor on line 5 column 11 and print the logical value of DISK1: $ RPOS 4 25 " Clearing Out Directory " - Position the cursor on line 4 column 25 and display the message " Clearing Out Directory " in REVERSE video. $ PDINQ 7 8 ANS "Run Program # 087 ==> " - Position cursor on line 7 column 8 and display the string "Run Program # 087 ==> " and the cursor will hold at the end of the string and wait for user input. $ PDINQ 7 8 ANS /SIZE=1/TIME "Run Program # 087 ==> " - Position cursor on line 7 column 8 and display the string "Run Program # 087 ==> " and the cursor will hold at the end of the string and wait for user input. /SIZE=1 option is used to allow only 1 character to be entered and the input will be terminated without the user be required to press the RETURN key. /TIME option allows the user the default of 10 minutes to enter a response .  S C R E E N C T L P R O G R A M F U N C T I O N S  Examples Continue ========= $ PDINQ 7 8 ANS /TIME=01:00 "Run Program # 087 ==> " - Position cursor on line 7 column 8 and display the string "Run Program # 087 ==> " and the cursor will hold at the end of the string and wait for user input. /TIME option allows the user 1 minute to enter a response. The form mm:ss is used to set the time limit. If values are less than 10, all zeros must be entered. Eg. Although 1 minute is allowed for a response, :00 must be entered to complete the proper syntax of the option. $ GETPF 15 20 P_F - Position the cursor on line 15 column 20 and wait for one of the 4 PF keys to be pressed. The symbol "P_F" will be set to a value of 1 thru 4 depending on which PF key is pressed. $ WINDOW 1 1 80 10 15 40 - Draw a box starting on line 1 column 1 across the screen for 80 columns and 10 lines deep, Also draw a horizontal line thru the box at line 15, and a vertical line thru the box in column 40. $ WINDOW 1 1 80 10 0 40 - Draw a box starting on line 1 column 1 across the screen for 80 columns and 10 lines deep, Also draw a vertical line thru the box in column 40 without drawing a horizontal line. $ WINDOW 1 1 80 20 4,15 20,40,60 - Draw a box starting on line 1 column 1 across the screen for 80 columns and 20 lines deep, Also draw two(2) horizontal lines, one on line 4 and the other on line 15. Then draw 3 vertical lines columns 20, 40 and 60.  S C R E E N C T L P R O G R A M F U N C T I O N S  TABLE 1 Key Symbol Value Returned F7 F7 F8 F8 F9 F9 F10 F10 F11 F11 F12 F12 F13 F13 F14 F14 F17 F17 F18 F18 F19 F19 F20 F20 FIND FIND INSERT HERE INSERT REMOVE REMOVE SELECT SELECT PREV SCREEN PREV NEXT SCREEN NEXT HELP HELP DO DO PF1 1 PF2 2 PF3 3 PF4 4 UP ARROW U DOWN ARROW D RIGHT ARROW R LEFT ARROW L Keypad Key Symbol Value Returned COMMA (,) COMMA PERIOD (.) PERIOD ENTER ENTER DASH (-) DASH Keys 0 thru 9 Return a value of 0 thru 9