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 dwn 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_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 POSITION -- CURSOR_COLUMN CURSOR_ROW FIND_CURSOR_DISPLAY HOME_CURSOR RETURN_CURSOR_POS SET_CURSOR_ABS SET_CURSOR_REL SET_PHYSICAL_CURSOR HIGH/WIDE CHARS -- PUT_CHARS_HIGHWIDE PUT_CHARS_WIDE PUT_LINE_WIDE LINE-DRAWING ----- DRAW_LINE DRAW_RECTANGLE 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_BPB_CHARACTERISTICS CHANGE_RENDITION CHANGE_VIRTUAL_DISPLAY CHECK_FOR_OCCLUSION CONTROL_MODE GET_CHAR_AT_PHYSICAL_CURSOR GET_DISPLAY_ATTR GET_PASTEBOARD_ATTRIBUTES PUT_VIRTUAL_DISPLAY_ENCODED READ_FROM_DISPLAY RING_BELL KEYBOARD --------- CANCEL_INPUT CREATE_VIRTUAL_KEYBOARD DELETE_VIRTUAL_KEYBOARD ENABLE_UNSOLICITED_INPUT DISABLE_UNSOLICITED_INPUT READ_COMPOSED_LINE READ_STRING SET_KEYPAD_MODE SET_OUT_OF_BAND_ASTS KEY DEFINITIONS -- ADD_KEY_DEF CREATE_KEY_TABLE DEFINE_KEY DELETE_KEY_DEF GET_KEY_DEF LIST_KEY_DEFS LOAD_KEY_DEFS READ_COMPOSED_LINE SET_DEFAULT_STATE TERMTABLE -------- DEL_TERM_TABLE GET_TERM_DATA INIT_TERM_TABLE INIT_TERM_TABLE_BY_TYPE ASTS ------------- ENABLE_UNSOLICITED_INPUT DISABLE_UNSOLICITED_INPUT SET_BROADCAST_TRAPPING SET_OUT_OF_BAND_ASTS BROADCAST -------- GET_BROADCAST_MESSAGE SET_BROADCAST_TRAPPING ADD_KEY_DEF (KTID,KEY-NAME,if-state,kattr,equiv-str,state-str) 474 Adds a key definition to a key table. KEY-NAMEs are defined below. ALLOW_ESCAPE (DID,ESC-FLAG) 476 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) 477 Starts batching of display changes, so user only sees final effect of multiple changes. See pg 3-20. BEGIN_PASTEBOARD_UPDATE (PBID) 478 Starts batching of pasteboard changes, so user only sees final effect of multiple changes. See pg 3-20. CANCEL_INPUT (KBID) 479 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) 480 Lets you change width, height, or background color of a paste- board. CHANGE_RENDITION (DID,STRT-ROW,STRT-COL,ROWS,COLS,rend,rendc) 483 Changes the default video rendition of a rectangular block of text already in a display. CHANGE_VIRTUAL_DISPLAY (DID,ROWS,COLS,border,rend) 486 Changes size or default attributes of an existing display. Border: 0=NO BORDER, 1=border CHECK_FOR_OCCLUSION (DID,PBID,OCCLUSION-STATE) 489 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) 491 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) 494 Creates a key table to hold your key definitions. CREATE_PASTEBOARD (NEW-PBID,device,rows,cols,preserve) 495 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=INITALLY CLEAR SCREEN, 1=do not initially clear CREATE_VIRTUAL_DISPLAY (ROWS,COLS,NEW-DID,border,rend) 497 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) 499 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) 501 Returns as the function result the cursor's current column in a display. CURSOR_ROW (DID) 502 Returns as the function result the cursor's current row in a display. DEL_TERM_TABLE 503 Terminates access to TERMTABLE.EXE and frees the associated virtual address space. DEFINE_KEY (KTID,COMMAND-LINE) 504 Parses and performs a DCL DEFINE /KEY command; the second arg- ument is the text of the command. DELETE_CHARS (DID,NUM-CHARS,ROW,COL) 506 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) 508 Deletes a key definition from a specified table of key defini- tions. DELETE_LINE (DID,START-LINE,number-lines) 510 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) 512 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) 513 Deletes display, removes it from any pasteboards on which it is pasted. All its buffer space is deallocated. DELETE_VIRTUAL_KEYBOARD (BKID) 514 Deletes virtual keyboard, resetting all terminal attributes and keypad mode. Channel is deassigned, any file is closed. DISABLE_UNSOLICITED_INPUT (PBID) 515 Disables unsolicited input ASTs. DRAW_LINE (DID,START-ROW,START-COL,END-ROW,END-COL,rend,rendc) 516 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) 519 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) 522 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) 524 Ends update batching for a display. See pg 3-20. END_PASTEBOARD_UPDATE (PBID) 525 Ends update batching for a pasteboard. See pg 3-20. ERASE_CHARS (DID,NUM-CHARS,ROW,COL) 526 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) 528 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) 530 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) 532 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) 533 Returns the I.D. of the display which contains the cursor. A zero is returned if no display contains it. FLUSH_BUFFER (PBID) 534 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) 535 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) 537 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) 539 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) 541 Returns the definition of a specified key and if-state. GET_PASTEBOARD_ATTRIBUTES (PBID,PB-INFO-TABLE,TABLE-SIZE) 543 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) 545 Accesses TERMTABLE.EXE for non-SMG I/O to terminal. HOME_CURSOR (DID ,position) 547 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) Initializes TERMTABLE database for non-SMG I/O to terminal. INIT_TERM_TABLE_BY_TYPE (TERM-TYPE,TERM-ENTRY,term-name) 551 Initializes TERMTABLE database for non-SMG I/O to terminal. INSERT_CHARS (DID,STRING,ROW,COL,rend,rendc) 553 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) 556 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) 559 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) 560 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) 563 Returns the definition associated with a specified key (or all keys) in a specified key table. LOAD_KEY_DEFS (KTID,FILE,default,logname-flag) 566 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) 568 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) 570 Places display on a pasteboard and makes the display visible. POP_VIRTUAL_DISPLAY (DID,PBID) 572 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) 573 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,erase,rend,rendc) 576 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,erase,rend,rendc) 579 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_VIRTUAL_DISPLAY_ENCODED (DID,LENGTH,TEXT,row,col,wrap) 582 Lets you output a string containing multiple video renditions. See description of ENCODED-TEXT on pg 582-583. PUT_LINE (DID,TEXT,line-adv,rend,rendc,wrap) 585 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_WIDE (DID,TEXT,line-adv,rend,rendc,wrap) 588 Same as PUT_LINE, except text is written using double-width characters. PUT_WITH_SCROLL (DID,text,scroll,rend,rendc,wrap) 591 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) 594 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) 597 Returns a string containing some or all of the text from the current line of the display. If TERMINATOR is not used, the string goes from the current column to the rightmost column. If TERMINATOR string is used, each character in it serves as a terminator for 'back-searching' (see pg 598). READ_STRING (KBID,TEXT,prompt,maxlen,modifiers,timeout, terminators,len,term-code,did) 599 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. REPAINT_SCREEN (PBID) 603 Repaints the screen after non-SMG I/O has occurred. REPASTE_VIRTUAL_DISPLAY (DID,PBID,PB-ROW,PB-COL) 604 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) 606 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) 607 Returns the current cursor position in a specified display. RING_BELL( DID,count) 609 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) 610 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) 612 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) 615 Enables or disables the trapping of broadcast messages. Trap- ping is disabled if AST-ROUTINE is omitted. SET_CURSOR_ABS (DID,row,col) 617 Moves the cursor to the specified position in a display. SET_CURSOR_REL (DID,delta-row,delta-col) 619 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) 621 Sets and/or returns the current default state for a key table. SET_DISPLAY_SCROLL_REGION (DID,start,end) 623 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) 625 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) 626 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) 628 Moves the cursor to the specified position on the pasteboard's physical screen. SNAPSHOT (PBID) 630 Writes the current pasteboard buffer to the file or hardcopy terminal specified by the pasteboard i.d. UNPASTE_VIRTUAL_DISPLAY (DID,PBID) 631 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