Previous | Contents |
Note that display batching for both the pasteboard and the virtual display must be off when you use SMG$READ_KEYSTROKE.
You can enter all keys on the VT100, VT200-series, and VT300-series keyboards with the following exceptions:
There are some keys and key definitions you can define, but Digital strongly suggests you avoid defining them. SMG$ does not return an error when you use these keys and key definitions, but the definitions you assign to these key combinations are not executed unless you set your terminal in the following special ways at the DCL level:
Digital does not recommend that you use these special terminal settings. The settings may cause unpredictable results if you do not understand all the implications of changing the default settings to give control to the terminal driver.
SS$_NORMAL Normal successful completion. SS$_ABORT I/O operation aborted during execution (by SMG$CANCEL_INPUT). SS$_CANCEL I/O operation canceled while queued (by SMG$CANCEL_INPUT). SS$_xxx Any error from $QIOW. SMG$_EOF End of file. SMG$_INVDIS_ID Invalid display-id. SMG$_INVKBD_ID Invalid keyboard-id. SMG$_WRONUMARG Wrong number of arguments. LIB$_xxx Any error from LIB$SCOPY_R_DX. RMS$_xxx Any error from $GET (except RMS$_EOF).
#1 |
---|
C+ C This DEC Fortran example program demonstrates the use of C SMG$READ_KEYSTROKE. C- C+ C This routine creates a virtual display and writes it to the pasteboard. C Data is placed in the virtual display using SMG$PUT_CHARS. C C First, include the SMG definitions. In particular, we want SMG$M_BORDER. C- IMPLICIT INTEGER (A-Z) INCLUDE '($SMGDEF)' CHARACTER*3 TEXT CHARACTER*27 TEXT_OUTPUT C+ C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual C display with a border. C- ROWS = 7 COLUMNS = 60 STATUS = SMG$CREATE_VIRTUAL_DISPLAY 1 (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) C+ C Create the pasteboard using SMG$CREATE_PASTEBOARD. C- STATUS = SMG$CREATE_PASTEBOARD ( PASTE1 ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) C+ C Use SMG$CREATE_VIRTUAL_KEYBOARD to create a virtual keyboard. C- STATUS = SMG$CREATE_VIRTUAL_KEYBOARD ( KEYBOARD1 ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) C+ C Using SMG$PASTE_VIRTUAL_DISPLAY, paste the virtual display C at row 3, column 9. C- STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 3, 9 ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) STATUS = SMG$PUT_LINE ( DISPLAY1, 1 'Enter the character K after the >> prompt.' ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) STATUS = SMG$PUT_LINE ( DISPLAY1, 1 'This character will not be echoed as you type it.' ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) STATUS = SMG$PUT_LINE ( DISPLAY1, 1 'The terminal character equivalent of K is displayed.' ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) STATUS = SMG$PUT_LINE ( DISPLAY1, ' ' ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) C+ C Call SMG$READ_KEYSTROKE to read a keystroke from the virtual C pasteboard. C- STATUS = SMG$READ_KEYSTROKE ( KEYBOARD1, TERM_CHAR, '>>', , 1 DISPLAY1 ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) STATUS = SMG$PUT_LINE ( DISPLAY1, ' ' ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) C+ C Use OTS$CVT_L_TI to convert the decimal value of TERM_CHAR to C a decimal ASCII text string. C- STATUS = OTS$CVT_L_TI ( TERM_CHAR, TEXT ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) TEXT_OUTPUT = ' TERMINAL CHARACTER IS: ' // TEXT C+ C Call SMG$PUT_LINE and SMG$PUT_CHARS to print the decimal C ASCII text string. C- STATUS = SMG$PUT_LINE ( DISPLAY1, TEXT_OUTPUT ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) STATUS = SMG$PUT_CHARS ( DISPLAY1, TEXT, 7, 25 ) IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) END |
The output generated by this FORTRAN program is shown in Figure SMG-37.
Figure SMG-37 Output Generated by FORTRAN Program Calling SMG$READ_KEYSTROKE
#2 |
---|
1 OPTION TYPE=EXPLICIT !+ ! This VAX BASIC program demonstrates the use of ! SMG$READ_KEYSTROKE to read a keystroke from the terminal. ! DECLARE LONG kb_id, ret_status, term_code, I, timer EXTERNAL SUB LIB$SIGNAL( LONG BY VALUE ) EXTERNAL SUB LIB$STOP( LONG BY VALUE ) EXTERNAL LONG CONSTANT SS$_TIMEOUT %INCLUDE "$SMGDEF" %FROM %LIBRARY "SYS$LIBRARY:BASIC$STARLET" EXTERNAL LONG FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD( LONG, STRING ) EXTERNAL LONG FUNCTION SMG$DELETE_VIRTUAL_KEYBOARD( LONG ) EXTERNAL LONG FUNCTION SMG$READ_KEYSTROKE( LONG, LONG, STRING, & LONG, LONG ) !+ ! Prompt the user for the timer value. A value of 0 will cause ! the type ahead buffer to be read. !- INPUT "Enter timer value (0 to read typeahead buffer): ";timer !+ ! Establish a SMG connection to SYS$INPUT. Signal any unexpected ! errors. !- ret_status = SMG$CREATE_VIRTUAL_KEYBOARD( kb_id, "SYS$INPUT:" ) IF (ret_status AND 1%) = 0% THEN CALL LIB$SIGNAL( ret_status ) END IF !+ ! Read a keystoke, tell the user what we found. !- ret_status = SMG$READ_KEYSTROKE( kb_id, term_code, , timer, ) IF (ret_status <> SS$_TIMEOUT) AND ((ret_status AND 1%) = 0%) THEN CALL LIB$SIGNAL( ret_status ) END IF PRINT "term_code = ";term_code SELECT term_code CASE 0 TO 31 PRINT "You typed a control character" CASE 32 TO 127 PRINT "You typed: ";CHR$(term_code) CASE SMG$K_TRM_PF1 TO SMG$K_TRM_PERIOD PRINT "You typed one of the keypad keys" CASE SMG$K_TRM_UP TO SMG$K_TRM_RIGHT PRINT "You typed one of the cursor positioning keys" CASE SMG$K_TRM_F6 TO SMG$K_TRM_F20 PRINT "You typed one of the function keys" CASE SMG$K_TRM_FIND TO SMG$K_TRM_NEXT_SCREEN PRINT "You typed one of the editing keys" CASE SMG$K_TRM_TIMEOUT PRINT "You did not type a key fast enough" CASE ELSE PRINT "I'm not sure what key you typed" END SELECT !+ ! Close the connection to SYS$INPUT, and signal any errors. !- ret_status = SMG$DELETE_VIRTUAL_KEYBOARD( kb_id ) IF (ret_status AND 1%) = 0% THEN CALL LIB$SIGNAL( ret_status ) END IF END |
This BASIC program reads a key and returns the word-terminator-code and the name of the keystroke entered. One sample of the commands entered and the output generated by this program is as follows:
$ RUN READ_KEY Enter the timer value (0 to read type-ahead buffer): ? 9 term_code = 100 You typed: dNote that in this example, the user entered the keystroke "d" following the first prompt. The keystroke entered was not echoed.
The Read String routine reads a string from a virtual keyboard.
SMG$READ_STRING keyboard-id ,resultant-string [,prompt-string] [,maximum-length] [,modifiers] [,timeout] [,terminator-set] [,resultant-length] [,word-terminator-code] [,display-id] [,initial-string] [,rendition-set] [,rendition-complement] [,terminator-string] [,character-set]
OpenVMS usage cond_value type longword (unsigned) access write only mechanism by value
keyboard-id
OpenVMS usage identifier type longword (unsigned) access read only mechanism by reference
Specifies the virtual keyboard from which input is to be read. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier.Keyboard-id is returned by SMG$CREATE_VIRTUAL_KEYBOARD.
resultant-string
OpenVMS usage char_string type character string access write only mechanism by descriptor
String into which the input line is written. The resultant-string argument is the address of a descriptor pointing to the string into which the text is written.prompt-string
OpenVMS usage char_string type character string access read only mechanism by descriptor
String used to prompt for the read operation. The prompt-string argument is the address of a descriptor pointing to the prompt string.maximum-length
OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference
Specifies the maximum number of bytes to be read. The maximum-length argument is the address of a signed longword that contains the maximum number of bytes to be read. The maximum valid value for this argument is 512. If omitted, 512 is the default.Note that as a result of truncation, the return string may be one byte shorter than maximum-length when the last byte is the left portion of Korean character.
modifiers
OpenVMS usage mask_longword type longword (unsigned) access read only mechanism by reference
Optional bit mask that specifies optional behavior. The modifiers argument is the address of an unsigned longword that contains the flag.Valid values for modifiers are as follows:
TRM$M_TM_CVTLOW Converts lowercase characters to uppercase. Only valid for ASCII and supplemental character set. TRM$M_TM_NOECHO Characters entered are not echoed on the screen. TRM$M_TM_PURGE Type-ahead buffer purged before read is done. TRM$M_TM_TRMNOECHO Terminator is not echoed. TRM$M_TM_NOEDIT Advanced editing is disabled. TRM$M_TM_NORECALL Line recall is disabled. The TRM$ symbols are defined by the $TRMDEF macro/module in Digital-supplied system symbol libraries.
timeout
OpenVMS usage longword_signed type longword (signed) access read only mechanism by reference
Specifies the number of seconds allowed between the time the prompt is issued and the completion of the input operation. The timeout argument is the address of a signed longword that contains the timeout value.If timeout is specified, all characters typed before the expiration time or until a terminate key is entered are returned in resultant-string. If omitted, the input operation remains active until a terminator is typed.
terminator-set
OpenVMS usage unspecified type unspecified access read only mechanism by descriptor, fixed length
Either a mask that specifies which characters are to be treated as terminators (short form) or a descriptor pointing to such a mask (long form). The terminator-set argument is the address of a descriptor pointing to the mask.If you want to use terminators with ASCII values in the range 0 to 31, use the short form, which consists of two longwords. The first longword is zero, and the second longword is a terminator character bit mask. You create this mask by setting the bit that corresponds to the ASCII value of the desired terminator. For example, to specify that Ctrl/A (ASCII value 1) is a terminator, you set bit 1 in the terminator-set mask.
If you want to use terminators with ASCII values outside the range 0 to 31, use the long form. First create a descriptor of this form:
The mask itself has the same format as that of the short form; however, the long form allows the use of a more comprehensive set of terminator characters. For example, a mask size of 16 bytes allows any 7-bit ASCII character to be set as a terminator, while a mask size of 32 bytes allows any 8-bit character to be set as a terminator. Any mask size between 1 and 32 bytes is acceptable.
If the terminator mask is all zeros, there are no specified terminators. In that case, the read terminates when the number of bytes specified in maximum-length has been transferred or when timeout is reached.
If the terminator-set argument is omitted, the set of terminators is the OpenVMS default terminator set.
OpenVMS usage | word_unsigned |
type | word (unsigned) |
access | write only |
mechanism | by reference |
OpenVMS usage | word_unsigned |
type | word (unsigned) |
access | write only |
mechanism | by reference |
OpenVMS usage | identifier |
type | longword (unsigned) |
access | read only |
mechanism | by reference |
If you are using the Screen Management Facility input and output routines, this argument specifies the virtual display in which the input is to occur. The virtual display specified must be pasted to the same pasteboard as specified by keyboard-id and must not be occluded. You cannot accept input from an occluded area of the virtual display.
In the case of multiple virtual displays, each virtual display has an associated virtual cursor position. At the same time, there is a single physical cursor position corresponding to the current location of the physical cursor. If the display-id argument is specified, the read begins at the current virtual cursor position in the specified virtual display. If display-id is omitted, the read begins in the current physical cursor position. Note that the length of the prompt-string plus the key entered is limited to the number of visible columns in the display.
This virtual display must be pasted in column 1 and may not have any other virtual displays to its right. This restriction applies because otherwise the occurrence of a Ctrl/R or Ctrl/U would cause the entire line to be blanked, including any output to the right. |
OpenVMS usage | char_string |
type | character string |
access | read only |
mechanism | by descriptor |
OpenVMS usage | mask_longword |
type | longword (unsigned) |
access | read only |
mechanism | by reference |
SMG$M_BLINK | Displays blinking characters. |
SMG$M_BOLD | Displays characters in higher-than-normal intensity (bolded). |
SMG$M_REVERSE | Displays characters in reverse video; that is, using the opposite default rendition of the virtual display. |
SMG$M_UNDERLINE | Displays underlined characters. |
SMG$M_INVISIBLE | Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard. |
SMG$M_USER1 through
SMG$M_USER8 |
Displays user-defined attributes. |
The display-id argument must be specified when you use the rendition-set argument.
OpenVMS usage | mask_longword |
type | longword (unsigned) |
access | read only |
mechanism | by reference |
The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display in which the read is done. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:
Set | Complement | Action |
---|---|---|
0 | 0 | Attribute set to default |
1 | 0 | Attribute on |
0 | 1 | Attribute set to complement of current setting |
1 | 1 | Attribute off |
OpenVMS usage | char_string |
type | character string |
access | write only |
mechanism | by descriptor |
OpenVMS usage | unsigned_longword |
type | longowrd (unsigned) |
access | read only |
mechanism | by reference |
Valid values for character-set are as follows:
Value | Character Set |
---|---|
SMG$C_ASCII | ASCII |
SMG$C_SPEC_GRAPHICS | DEC Special Graphics |
SMG$C_HANGUL | DEC Hangul |
Refer to Table 2-1 in Section 2.2.14 for the valid definitions of the SMG$DEFAULT_CHARACTER_SET logical name.
SMG$READ_STRING returns a string of characters read from a virtual keyboard. Note that display batching for both the pasteboard and the virtual display must be off when you use SMG$READ_STRING.The text read by SMG$READ_STRING is saved for later recall with SMG$READ_COMPOSED_LINE. Rendition applies to both the prompt (if there is one) and echoing of input characters.
SS$_NORMAL Normal successful completion. SS$_ABORT I/O operation aborted during execution (by SMG$CANCEL_INPUT). SS$_CANCEL I/O operation canceled while queued (by SMG$CANCEL_INPUT). SMG$_EOF End of file. SMG$_ILLBATFNC Input not allowed from a batched display. SMG$_INVARG Invalid argument. SMG$_INVCOL Invalid column. The input occurs outside the virtual display. SMG$_INVDIS_ID Invalid display-id. SMG$_INVKBD_ID Invalid keyboard-id. SMG$_INVKTB_ID Invalid key-table-id. SMG$_INVMAXLEN Maximum length specified was greater than 512. SMG$_WRONUMARG Wrong number of arguments.
Previous | Next | Contents |