SUMMARY OF VAX RUN TIME LIBRARY   SCREEN MANAGEMENT ROUTINES  BASIC ROUTINES --- CREATE_PASTEBOARD CREATE_VIRTUAL_DISPLAY PASTE_VIRTUAL_DISPLAY DELETE_PASTEBOARD COMPOSITION ------ DELETE_CHARS delete chars, shifting rest left ERASE_CHARS replace chars with blanks DELETE_LINE delete lines, display scrolls ERASE_LINE replace line with blanks INSERT_CHARS insert chars, shifting rest right PUT_CHARS write chars, overwriting existing text INSERT_LINE insert line, scrolling rest up or down PUT_LINE write line at col 1 of cursor's row PUT_WITH_SCROLL like PUT_LINE, but display scrolls THE BIG PICTURE -- DELETE_VIRTUAL_DISPLAY remove from pb, deallocate UNPASTE_VIRTUAL_DISPLAY removes, but saves ERASE_DISPLAY blank all or part of a display ERASE_PASTEBOARD erases screen until next output INVALIDATE_DISPLAY mark display as invalid REPASTE_VIRTUAL_DISPLAY move, changing paste order MOVE_VIRTUAL_DISPLAY move, preserving paste order POP_VIRTUAL_DISPLAY DELETEs this, newer displays REPAINT_LINE repaints selected lines REPAINT_SCREEN repaints current screen SAVE_PHYSICAL_SCREEN saves, then blanks area RESTORE_PHYSICAL_SCREEN restores SAVEd area SCROLL_DISPLAY_AREA scrolls rectangular region SET_DISPLAY_SCROLL_REGION creates scrolling region SNAPSHOT sends pb contents to file or non-SMG term CURSOR -- CURSOR_COLUMN HIGH/WIDE -- PUT_CHARS_HIGHWIDE CURSOR_ROW PUT_CHARS_WIDE FIND_CURSOR_DISPLAY PUT_LINE_HIGHWIDE HOME_CURSOR PUT_LINE_WIDE RETURN_CURSOR_POS SET_CURSOR_ABS LINE DRAWING -- DRAW_LINE SET_CURSOR_REL DRAW_RECTANGLE SET_PHYSICAL_CURSOR LABEL_BORDER BATCHING OUTPUT -- BEGIN_DISPLAY_UPDATE END_DISPLAY_UPDATE BEGIN_PASTEBOARD_UPDATE END_PASTEBOARD_UPDATE FLUSH_BUFFER (see CONTROL_MODE) MISCELLANEOUS ---- ALLOW_ESCAPE CHANGE_PBD_CHARACTERISTICS CHANGE_RENDITION CHANGE_VIRTUAL_DISPLAY CHECK_FOR_OCCLUSION CONTROL_MODE GET_CHAR_AT_PHYSICAL_CURSOR GET_DISPLAY_ATTR GET_PASTEBOARD_ATTRIBUTES PUT_PASTEBOARD PUT_VIRTUAL_DISPLAY_ENCODED READ_FROM_DISPLAY RING_BELL KEYBOARD -- CANCEL_INPUT KEYS -- ADD_KEY_DEF CREATE_VIRTUAL_KEYBOARD CREATE_KEY_TABLE DELETE_VIRTUAL_KEYBOARD DEFINE_KEY ENABLE_UNSOLICITED_INPUT DELETE_KEY_DEF DISABLE_UNSOLICITED_INPUT GET_KEY_DEF READ_COMPOSED_LINE LIST_KEY_DEFS READ_KEYSTROKE LOAD_KEY_DEFS READ_STRING READ_COMPOSED_LINE READ_VERIFY SET_DEFAULT_STATE SET_KEYPAD_MODE SET_OUT_OF_BAND_ASTS ASTS -- ENABLE_UNSOLICITED_INPUT TERMTABLE -- DEL_TERM_TABLE DISABLE_UNSOLICITED_INPUT GET_TERM_DATA SET_BROADCAST_TRAPPING GET_NUMERIC_DATA SET_OUT_OF_BAND_ASTS INIT_TERM_TABLE INIT_TERM_TABLE_ BY_TYPE BROADCAST -- GET_BROADCAST_MESSAGE SET_BROADCAST_TRAPPING ADD_KEY_DEF (KTID,KEY-NAME,if-state,kattr,equiv-str,state-str) 538 Adds a key definition to a key table. KEY-NAMEs are defined below. ALLOW_ESCAPE (DID,ESC-FLAG) 541 If ESC-FLAG=1, allows text written to a display to contain es- cape sequences (normally escape sequences are not allowed). If ESC-FLAG=0, escape sequences are disallowed. BEGIN_DISPLAY_UPDATE (DID) 543 Starts batching of display changes, so user only sees final effect of multiple changes. See pg 3-20. BEGIN_PASTEBOARD_UPDATE (PBID) 544 Starts batching of pasteboard changes, so user only sees final effect of multiple changes. See pg 3-20. CANCEL_INPUT (KBID) 545 Causes READ_STRING or READ_COMPOSED_LINE to terminate with the condition SS$_CANCEL (unless KBID is an RMS disk file). CHANGE_PBD_CHARACTERISTICS (PBID,desired-width,result-width, desired-height,result-height, des-bckgnd-color,res-bg-color) 546 Lets you change width, height, or background color of a paste- board. CHANGE_RENDITION (DID,STRT-ROW,STRT-COL,ROWS,COLS,rend,rendc) 549 Changes the default video rendition of a rectangular block of text already in a display. CHANGE_VIRTUAL_DISPLAY (DID,ROWS,COLS,border,rend) 552 Changes size or default attributes of an existing display. Border: 0=NO BORDER, 1=border CHECK_FOR_OCCLUSION (DID,PBID,OCCLUSION-STATE) 555 Checks if a display is covered by another display. The argu- ment OCCLUSION-STATE is set to 1 if so, 0 if not. CONTROL_MODE (PBID,new-mode,old-mode) 558 Allows interrogation or changing of a pasteboard's operation. The mode bits are: 1 = Enable buffering (see FLUSH_BUFFER) 2 = Enable minimum update (on by default) 4 = Clear screen when pasteboard deleted (on by default) 8 = Use no tabs You should call CONTROL_MODE twice, first getting the old set- tings, then changing the desired bits on the second call. CREATE_KEY_TABLE (NEW-KTID) 561 Creates a key table to hold your key definitions. CREATE_PASTEBOARD (NEW-PBID,device,rows,cols,preserve) 562 Creates a pasteboard. DEVICE (default SYS$OUTPUT) is the file or terminal to which the pasteboard's output will be written. ROWS and COLS are values returned by this routine. preserve: 0=INITIALLY CLEAR SCREEN, 1=do not initially clear CREATE_VIRTUAL_DISPLAY (ROWS,COLS,NEW-DID,border,rend) 565 Creates a new display, returns its DID. The cursor is put at the display's upper left corner. 0=NO BORDER, 1=border CREATE_VIRTUAL_KEYBOARD (NEW-KBID,file,default,resultant) 569 Associates a terminal or an RMS file with a virtual keyboard. This is required before READ_STRING or READ_COMPOSED_LINE is used. Keyboard is set to application mode and line editing. CURSOR_COLUMN (DID) 572 Returns as the function result the cursor's current column in a display. CURSOR_ROW (DID) 573 Returns as the function result the cursor's current row in a display. DEFINE_KEY (KTID,COMMAND-LINE) 574 Parses and performs a DCL DEFINE /KEY command; the second arg- ument is the text of the command. DEL_TERM_TABLE 576 Terminates access to TERMTABLE.EXE and frees the associated virtual address space. DELETE_CHARS (DID,NUM-CHARS,ROW,COL) 577 Deletes specified number of character; remaining characters on the line are shifted left. Cursor is left at position of fir- st character deleted. DELETE_KEY_DEF (KTID,KEY-NAME,if-state) 581 Deletes a key definition from a specified table of key defini- tions. DELETE_LINE (DID,START-LINE,number-lines) 583 Deletes one or more lines, scrolls remaining lines up; blank lines fill display on bottom. Cursor is left at first column of starting line. DELETE_PASTEBOARD (PBID,clear-screen-flag) 586 Flushes all output to display, terminates use of pasteboard, and deallocates all associated resources. Clear-screen-flag: 1=CLEAR, 0=don't clear DELETE_VIRTUAL_DISPLAY (DID) 587 Deletes display, removes it from any pasteboards on which it is pasted. All its buffer space is deallocated. DELETE_VIRTUAL_KEYBOARD (KBID) 588 Deletes virtual keyboard, resetting all terminal attributes and keypad mode. Channel is deassigned, any file is closed. DISABLE_UNSOLICITED_INPUT (PBID) 589 Disables unsolicited input ASTs. DRAW_LINE (DID,START-ROW,START-COL,END-ROW,END-COL,rend,rendc) 590 Uses line-drawing set to draw a line. Any intersections with previously-drawn lines are correctly drawn. The cursor posi- tion does not change. DRAW_RECTANGLE (DID,TL-ROW,TL-COL,BR-ROW,BR-COL,rend,rendc) 594 Uses line-drawing set to draw a box. Any intersections with previously-drawn lines are correctly drawn. The cursor posi- tion does not change. ENABLE_UNSOLICITED_INPUT (PBID,AST-ROUTINE,ast-arg) 598 Enables AST to be called (with two arguments PBID and AST-ARG; note PBID is passes by immediate value) when unsolicited input is detected. No characters are actually read. END_DISPLAY_UPDATE (DID) 600 Ends update batching for a display. See pg 3-20. END_PASTEBOARD_UPDATE (PBID) 601 Ends update batching for a pasteboard. See pg 3-20. ERASE_CHARS (DID,NUM-CHARS,ROW,COL) 602 Erases characters by replacing them with blanks. The cursor is left at the first character erased. ERASE_DISPLAY (DID,start-row,start-col,end-row,end-col) 606 Erases all or part of a display by replacing text with blanks. The 'start' arguments default to '1,1' and the 'end' arguments default to the ending positions of the display. The cursor is left at the first position after the erased portion, or at 1,1 if all was erased. ERASE_LINE (DID,line,col) 610 Erases a line from the specified starting position to the end of the line. The cursor is left at the first blank after the erased text. ERASE_PASTEBOARD (PBID) 614 Erases a pasteboard; i.e. clears the screen. Cursor is left at 1,1. If there are any pasted displays, they will be redrawn the next time SMG outputs to the pasteboard. FIND_CURSOR_DISPLAY (PBID,RETURNED-DID) 616 Returns the I.D. of the display which contains the cursor. A zero is returned if no display contains it. FLUSH_BUFFER (PBID) 617 Flushes all buffered output to the terminal. Used only when buffering enabled (see CONTROL_MODE and pg 3-20). GET_BROADCAST_MESSAGE (PBID,message,message-len) 618 Determines if a message has been broadcast and returns it if so. Function result is SS$_NORMAL or SMG$_NO_MORMSG; both are SUCCESS values. Broadcast trapping must be enabled by routine SET_BROADCAST_TRAPPING. GET_CHAR_AT_PHYSICAL_CURSOR (PBID,CHARACTER) 620 Returns character at current screen physical cursor position. Hex FF is returned if SMG has not written there. Values < 20 hex are internal codes and should not be used for output. GET_DISPLAY_ATTR (DID,HEIGHT,WIDTH,border,rend) 622 Returns a display's attributes: height, width, border presen- ce (0=no border, 1=border), default video attributed. GET_KEY_DEF (KTID,KEY-NAME,if-state,kattr,equiv-str,state-str) 624 Returns the definition of a specified key and if-state. GET_NUMERIC_DATA (TTBL-ADDR,REQ-CODE,BUFADR) 627 NEW Returns numeric sequence that causes a terminal to perform a specified operation. GET_PASTEBOARD_ATTRIBUTES (PBID,PB-INFO-TABLE,TABLE-SIZE) 629 Gets pasteboard's attributes and stores them in a table. You must specify 32 as table-size. The table contents are: Bytes 0 - 3 -- DEVCHAR 4 - 7 -- DEVDEPEND 8 - 11 -- DEVDEPEND2 12 -- DEVCLASS (DC$_TERM, etc.) 13 -- Internal SMG device type 14 -- DEVTYPE (DT$_VT100, etc.) 15 -- Number of rows 16 - 17 -- Width 18 -- (reserved) 19 -- PARITY 20 - 21 -- SPEED 22 - 23 -- FILL 24 - 25 -- Row containing physical cursor 26 - 27 -- Column containing physical cursor 28 - 31 -- I.D. of display containing physical cursor GET_TERM_DATA (TTBL-ADDR,REQ-CODE,MAX-BUF-LEN,RET-LEN,BUFADR, in-arg-vec) 631 Accesses TERMTABLE.EXE for non-SMG I/O to terminal. HOME_CURSOR (DID ,position) 633 Moves cursor to specified corner of a display. 0=UPPER LEFT, 1=lower left, 2=upper right, 3=lower right INIT_TERM_TABLE (TERM-NAME,TERM-ENTRY-ADDR) 635 Initializes TERMTABLE database for non-SMG I/O to terminal. INIT_TERM_TABLE_BY_TYPE (TERM-TYPE,TERM-ENTRY,term-name) 637 Initializes TERMTABLE database for non-SMG I/O to terminal. INSERT_CHARS (DID,STRING,ROW,COL,rend,rendc) 639 Inserts string at specified row and column. Characters to the right are shifted right. Cursor remains at position following the last character inserted. INSERT_LINE (DID,LINE,string,scroll,rend,rendc,wrap) 644 Inserts a line into a display and scrolls the display. Cursor remains at position following the last character written. 1=SCROLL UP, 2=down; 0=NO WRAP, 1=wrap INVALIDATE_DISPLAY (DID) 649 Marks display as invalid and causes it to be redrawn the next time SMG writes to pasteboard containing the display. You use this after you determine that output has been written without using SMG. LABEL_BORDER (DID,text,positn,units,rend,rendc) 650 Supplies a label for a display's border (a border is forced if not present). Null text causes border to be unlabeled. The status SMG$_INVARG is returned if label text is too long. The UNITS argument gives label's starting row or column position in the border; if omitted, label is centered. 0=TOP, 1=bottom, 2=left, 3=right LIST_KEY_DEFS (KTID,CONTEXT,key-name,if-state,kattr,equiv-str, state-str) 655 Returns the definition associated with a specified key (or all keys) in a specified key table. LOAD_KEY_DEFS (KTID,FILE,default,logname-flag) 658 Loads a set of key definitions (DCL DEFINE/KEY commands) from a file into a specified key table. MOVE_VIRTUAL_DISPLAY (DID,PBID,PB-ROW,PB-COL) 660 Relocates a display on a pasteboard, preserving pasting order. If display is not currently pasted, it is pasted at the top of the pasting order. The row and col arguments tell where the top left corner is to be moved. PASTE_VIRTUAL_DISPLAY (DID,PBID,PB-ROW,PB-COL) 662 Places display on a pasteboard and makes the display visible. POP_VIRTUAL_DISPLAY (DID,PBID) 665 Deletes specified display and all displays pasted after it on the specified pasteboard. Displayed are DELETED, not just UN- PASTED. PUT_CHARS (DID,TEXT,row,col,erase,rend,rendc) 667 Writes text to display, overwriting any existing text. If row and col are not specified, output begins at current cursor lo- cation. If ERASE flag is on, line is erased first. Cursor is left following the last text written. PUT_CHARS_HIGHWIDE (DID,TEXT,row,col,rend,rendc) 671 Same as PUT_CHARS, except text is written using double-height, double-width, characters. Any existing text on same paste- board line is rewritten in this size. PUT_CHARS_WIDE (DID,TEXT,row,col,rend,rendc) 674 Same as PUT_CHARS, except text is written using double-width characters. Any existing text on same pasteboard line is re- written in this size. PUT_LINE (DID,TEXT,line-adv,rend,rendc,wrap) 677 Writes a line of text, starting in column 1. The line is pad- ded with blanks if it is narrower than the display; any excess characters are discarded if the line is too long and the WRAP flag is not set. LINE-ADV (default 1) controls the number of lines to advance after output; the cursor is left at column 1 of the resultant line. 0=NO WRAP, 1=wrap PUT_LINE_HIGHWIDE (DID,TEXT,line-adv,rend,rendc,wrap) 681 NEW Same as PUT_LINE, except text is written using double-high/ double-wide characters. PUT_LINE_WIDE (DID,TEXT,line-adv,rend,rendc,wrap) 684 Same as PUT_LINE, except text is written using double-wide characters. PUT_PASTEBOARD (PBID,P-ROUTINE,p-arg,p-ff-flag) 689 NEW Outputs the contents of a pasteboard via a user-specified rou- tine. PUT_VIRTUAL_DISPLAY_ENCODED (DID,LENGTH,TEXT,row,col,wrap) 691 Lets you output a string containing multiple video renditions. See description of ENCODED-TEXT on pg 582-583. PUT_WITH_SCROLL (DID,text,scroll,rend,rendc,wrap) 694 Writes text to the display beginning at the current line. When text reaches the bottom (or top, depending on SCROLL), subse- quent calls to this routine cause the display to scroll. If no text is supplied, a blank line opens up. This is NOT used to insert a line in the middle of a display and scroll; you must use SCROLL_DISPLAY_AREA then write to the beginning of the new scrolling region. 1=SCROLL UP, 2=down; 0=NO WRAP, 1=wrap READ_COMPOSED_LINE (KBID,KTID,TEXT,prompt,len,did,func-keys) 698 Reads a line of input composed of normal keystrokes and equiv- alence strings of keypad keys, etc. See below for codes of special characters not equivalenced in KTID key table. READ_FROM_DISPLAY (DID,STRING,terminator,row) 701 Returns a string containing some or all of the text from the specified row (default current row) of the display. If TERM- INATOR is not used, the string goes from the current column to the rightmost column. If TERMINATOR string is used, each char- acter in it serves as a terminator for 'back-searching' (see pg 702). READ_KEYSTROKE (KBID,TERM-CODE,prompt,timeout,did) 705 NEW Reads a keystroke and returns the keystroke's terminator code. The keystroke is not echoed. READ_STRING (KBID,TEXT,prompt,maxlen,modifiers,timeout, terminators,len,term-code,did,ini-string) 710 Reads a string from a virtual keyboard. MODIFIERS can be any accepted by IO$_READVBLK. Using TERMINATORS you can specify what terminates a read (see below). LEN is number of charac- ters read, and TERM-CODE is code of terminator (see below). IF only ASCII characters 00-31 (dec) are terminators, pass the TERMINATORS argument by reference; it is a two-longword array with first longword zero, and mask in second longword. Other- wise, pass TERMINATORS by descriptor, and create it as a mask up to 256 bits long. The default VMS terminators are all characters in the range 0 through 31 except backspace (8), tab (9), line feed (10), ver- tical tab (11), and form feed(12). I cannot get by itself to work as a terminator. READ_VERIFY (KBID,OUTSTR,INSTR,PICSTR,FILL,CLEAR,prompt, modifiers,timeout,terminators,ini-offset, term-code,did,alt-echo,alt-did) 718 NEW Reads a sequence of characters and verifies the sequence. See the I/O Reference Manual for description of Read Verify. REPAINT_LINE (PBID,ROW-STRT,rows) 723 NEW Repaints a series of lines after non-SMG I/O has occurred. REPAINT_SCREEN (PBID) 725 Repaints the screen after non-SMG I/O has occurred. REPASTE_VIRTUAL_DISPLAY (DID,PBID,PB-ROW,PB-COL) 728 Moves a display to a new position on the pasteboard. Pasting order is not preserved. (Use MOVE_VIRTUAL_DISPLAY to move a display without changing its pasting order.) RESTORE_PHYSICAL_SCREEN (PBID,SAVED-DID) 732 Reproduces the screen image saved by SAVE_PHYSICAL_SCREEN. The SAVED-DID integer argument is the value returned by routine SAVE_PHYSICAL_SCREEN. RETURN_CURSOR_POS (DID,ROW,COL) 733 Returns the current cursor position in a specified display. RING_BELL( DID,count) 735 Sounds the bell on each pasteboard to which the specified dis- play is pasted. The bell sounds the number of times specified (default 1). SAVE_PHYSICAL_SCREEN (PBID,SAVED-DID,row-strt,row-end) 736 Saves the screen contents so routine RESTORE_PHYSICAL_SCREEN can be called later to restore it. The specified rows (default entire screen) are saved, and blanked. This routine sets arg- ument SAVED-DID; this value must be passed to routine RESTORE_PHYSICAL_SCREEN. SCROLL_DISPLAY_AREA (DID,row,col,height,width,direction,count) 738 Scrolls a rectangular region of the specified display. Both or neither ROW and COL must be specified (default is 1,1). WIDTH defaults to the display width, and HEIGHT defaults to the en- tire display, unless SET_DISPLAY_SCROLL_REGION was called to define a scrolling region. COUNT is number of lines (or col- umns) to scroll. UP=1, down=2, left=8, right=4 SET_BROADCAST_TRAPPING (PBID,ast-routine,ast-arg) 741 Enables or disables the trapping of broadcast messages. Trap- ping is disabled if AST-ROUTINE is omitted. SET_CURSOR_ABS (DID,row,col) 743 Moves the cursor to the specified position in a display. SET_CURSOR_REL (DID,delta-row,delta-col) 745 Moves the cursor the specified number of rows and/or columns from its current position in a display. SET_DEFAULT_STATE (KTID,new-state,old-state) 747 Sets and/or returns the current default state for a key table. SET_DISPLAY_SCROLL_REGION (DID,start,end) 749 Creates a scrolling region in a display. If START and/or END are omitted, then top and/or bottom lines of the display are used. SET_KEYPAD_MODE (KBID,NEW-MODE) 751 Sets the terminal's numeric keypad to either numeric or appli- cation mode. odd=numeric, even=application SET_OUT_OF_BAND_ASTS (PBID,MASK,AST-ROUTINE,ast-arg) 753 Enables or disables trapping of out-of-band characters. If no bits are set in MASK, no out-of-band ASTs occur. AST-ROUTINE is called with a three-longword argument: 1. Pasteboard id 2. AST-ARG 3. ASCII value of character (blank filled on left) MASK BITS = .... .ZYX WVUT SRQP ONML KJIH GFED CBA. 0 2 0 0 0 0 0 0 = control-y SET_PHYSICAL_CURSOR (PBID,ROW,COL) 755 Moves the cursor to the specified position on the pasteboard's physical screen. SNAPSHOT (PBID) 757 Writes the current pasteboard buffer to the file or hardcopy terminal specified by the pasteboard i.d. UNPASTE_VIRTUAL_DISPLAY (DID,PBID) 758 Removes a virtual display from a pasteboard, and thus from the screen. Any text hidden by the display becomes visible again. The display or its contents is not destroyed; it can be pasted again. --- DEFINITIONS OF COMMON ARGUMENTS ---------------------------------- rend -- logical or of: 1=bold 2=reverse 4=blink 8=underline rend/rendc -- rend bit=0, rendc bit=0 - attribute unchanged 1 0 attribute on 0 1 attr set to -(default) 1 1 attribute off kattr -- logical or of: 1=noecho 2=terminate 4=lockstate 8=protect --- KEY NAMES AND TERMINATOR CODES ----------------------------------- PF1 256 ENTER 270 F12 292 PF2 257 MINUS 271 F13 293 PF3 258 COMMA 272 F14 294 PF4 259 PERIOD 273 HELP 295 KP0 260 UP 274 DO 296 KP1 261 DOWN 275 F17 297 KP2 262 LEFT 276 F18 298 KP3 263 RIGHT 277 F19 299 KP4 264 F6 286 F20 300 KP5 265 F7 287 FIND 311 KP6 266 F8 288 INSERT_HERE 312 KP7 267 F9 289 REMOVE 313 KP8 268 F10 290 SELECT 314 KP9 269 F11 291 PREV_SCREEN 315 NEXT_SCREEN 316 cancelled 508 , timeout 509 , buffer_full 510 , unknown 511