 |
OpenVMS RTL Screen Management (SMG$) Manual
SMG$RESTORE_PHYSICAL_SCREEN
The Restore Physical Pasteboard routine rewrites the pasteboard image
as it was at the time the SMG$SAVE_PHYSICAL_SCREEN routine was called.
Format
SMG$RESTORE_PHYSICAL_SCREEN pasteboard-id ,display-id
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
pasteboard-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the pasteboard to be restored. The
pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
The pasteboard identifier is returned by the SMG$CREATE_PASTEBOARD
routine.
display-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the virtual display created by the SMG$SAVE_PHYSICAL_SCREEN
routine. The display-id argument is the address of an
unsigned longword that contains this display identifier.
Description
SMG$RESTORE_PHYSICAL_SCREEN reproduces the pasteboard image saved by
the SMG$SAVE_PHYSICAL_SCREEN routine. You must pass the
display-id returned by the SMG$SAVE_PHYSICAL_SCREEN
routine to the SMG$RESTORE_PHYSICAL_SCREEN routine. Note that when
performing multiple calls to SMG$SAVE_PHYSICAL_SCREEN and
SMG$RESTORE_PHYSICAL_SCREEN, the calls must be performed in a nested
fashion; that is, the last pasteboard saved must be the first one
restored.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_INVPAS_ID
|
Invalid
pasteboard-id.
|
SMG$RETURN_CURSOR_POS
The Return Cursor Position routine returns the current virtual cursor
position in a specified virtual display.
Format
SMG$RETURN_CURSOR_POS display-id ,start-row ,start-column
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
display-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the virtual display whose current virtual cursor position you
are requesting. The display-id argument is the address
of an unsigned longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
start-row
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
write only |
| mechanism: |
by reference |
Receives the virtual cursor's current row position within the specified
virtual display. The start-row argument is the address
of a signed longword into which is written the current row position.
start-column
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
write only |
| mechanism: |
by reference |
Receives the virtual cursor's current column position within the
specified virtual display. The start-column argument
is the address of a signed longword into which is written the current
column position.
Description
SMG$RETURN_CURSOR_POS returns the virtual cursor's current row and
column positions in a specified virtual display.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
SMG$RETURN_INPUT_LINE
The Return Input Line routine returns to the caller the requested line
from the recall buffer. This line is retrieved either by matching it
with a specified string or by specifying the appropriate line number.
Format
SMG$RETURN_INPUT_LINE keyboard-id ,resultant-string [,match-string]
[,byte-integer-line-number] [,resultant-length]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
keyboard-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Keyboard identifier. The keyboard-id argument is the
address of an unsigned longword containing the identifier of the
virtual keyboard from which to read.
The virtual keyboard is created by calling the
SMG$CREATE_VIRTUAL_KEYBOARD routine.
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
String into which is written the complete recalled line. The
resultant-string argument is the address of a
descriptor pointing to this string.
match-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Match string to be used when searching for the line to be recalled. The
optional match-string argument is the address of a
descriptor pointing to this match string. The search begins with the
last line typed.
byte-integer-line-number
| OpenVMS usage: |
byte_unsigned |
| type: |
byte (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Line number to be used when searching for the line to be recalled. The
optional byte-integer-line-number argument is the
address of an unsigned byte containing the number of the line to be
recalled. The last line typed is line number 1.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Length of the resultant-string string. The optional
resultant-length argument is the address of an
unsigned word containing either the number of characters read or the
maximum length of resultant-string, whichever is less.
Description
SMG$RETURN_INPUT_LINE returns to the caller the specified line in the
recall buffer. This routine aids in an implementation similar to the
DCL command RECALL.
If you specify the match-string argument,
SMG$RETURN_INPUT_LINE searches for and returns the line that matches
the specified string. If you specify the
byte-integer-line-number argument,
SMG$RETURN_INPUT_LINE returns the line that corresponds to the
specified line number. If you specify both
match-string and
byte-integer-line-number, SMG$_INVARG is returned. If
you specify match-string and a match is not made,
SMG$_LINNOTFND is returned.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVARG
|
Invalid argument.
|
|
SMG$_INVKBD_ID
|
Invalid
keyboard-id.
|
|
SMG$_LINNOTFND
|
Matching line was not found.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
|
LIB$_
xxx
|
Any error from LIB$SCOPY_R_DX.
|
Example
|
!+
! This FORTRAN example uses the routine
! SMG$RETURN_INPUT_LINE to implement a
! RECALL/ALL command.
!-
IMPLICIT INTEGER (A-Z)
INCLUDE '($SMGDEF)'
INCLUDE '($SMGMSG)'
CHARACTER*20 TEXT
WRITE (5,*) 'Enter number of lines to save.'
READ (5,*) R
S = SMG$CREATE_PASTEBOARD(PBID)
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
S = SMG$CREATE_VIRTUAL_DISPLAY(22,70,DID,SMG$M_BORDER)
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
S = SMG$CREATE_VIRTUAL_KEYBOARD(KBID,,,,R)
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
S = SMG$PUT_LINE(DID,'Enter lines of text:')
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
S = SMG$PASTE_VIRTUAL_DISPLAY(DID,PBID,2,2)
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
!+
! Read in lines of text.
!-
DO 10 I = 1,R
S = SMG$READ_COMPOSED_LINE(KBID,,TEXT,'Example>',,DID)
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
10 CONTINUE
S = SMG$PUT_LINE(DID,'**** The lines of text are:')
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
!+
! Recall all lines in the buffer.
!-
DO 30 N = 1,R
S = SMG$RETURN_INPUT_LINE(KBID,TEXT,,N)
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
S = SMG$PUT_LINE(DID,TEXT)
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
30 CONTINUE
!+
! Recall the line containing 'fox'
!-
S = SMG$PUT_LINE(DID,'**** The line containing "fox" is:',2)
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
S = SMG$RETURN_INPUT_LINE(KBID,TEXT,'FOX')
IF (S .EQ. SMG$_LINNOTFND) TEXT = 'None found!'
S = SMG$PUT_LINE(DID,TEXT)
IF (.NOT. S) CALL LIB$STOP(%VAL(S))
END
|
One sample of the output generated by this Fortran program is as
follows:
$ RUN RETURN
Enter number of lines to save.
3
Enter lines of text:
Example> PASTEBOARD
Example> DISPLAY
Example> KEYBOARD
****The lines of text are:
KEYBOARD
DISPLAY
PASTEBOARD
****The line containing "fox" is:
None found!
|
SMG$RING_BELL
The Ring the Terminal Bell or Buzzer routine sounds the terminal bell
or buzzer.
Format
SMG$RING_BELL display-id [,number-of-times]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
display-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the virtual display for which the bell or buzzer sounds. The
display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
number-of-times
| OpenVMS usage: |
longword_signed |
| type: |
longword integer (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the number of times the bell or buzzer is sounded. The
number-of-times argument is the address of a signed
longword integer that contains the number of times the bell or buzzer
is sounded. If number-of-times is omitted, 1 is used.
Description
SMG$RING_BELL sounds the bell or buzzer on each pasteboard to which the
specified virtual display is pasted. The bell or buzzer sounds the
number of times specified; the default number of times is 1.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
Any condition values returned by $QIOW, LIB$GET_VM, LIB$FREE_VM.
SMG$SAVE_PHYSICAL_SCREEN
The Save Physical Screen routine saves the contents of the pasteboard
so that a later call to SMG$RESTORE_PHYSICAL_SCREEN can restore it.
Format
SMG$SAVE_PHYSICAL_SCREEN pasteboard-id ,display-id [,desired-start-row]
[,desired-end-row]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
pasteboard-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the pasteboard whose contents are to be saved. The
pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
display-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Receives the display identifier of the display created to contain the
contents of the specified pasteboard. The display-id
argument is the address of an unsigned longword into which the display
identifier is written.
The display identifier must be passed to the
SMG$RESTORE_PHYSICAL_SCREEN routine to restore the saved information.
desired-start-row
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the first row to be saved. The
desired-start-row argument is the address of a signed
longword that contains the row number. If
desired-start-row is omitted, row 1 of the pasteboard
is used.
desired-end-row
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the last row to be saved. The
desired-end-row argument is the address of a signed
longword that contains the row number. If
desired-end-row is omitted, the last row of the
pasteboard is used.
Description
SMG$SAVE_PHYSICAL_SCREEN blanks the screen by creating a virtual
display that is as wide as the specified pasteboard and as high as
specified by the desired-start-row and
desired-end-row arguments. If these two arguments are
omitted, the created virtual display is as high as the specified
pasteboard. The information saved --- that is, the pasteboard image ---
can be restored by calling the SMG$RESTORE_PHYSICAL_SCREEN routine.
When performing multiple calls to SMG$SAVE_PHYSICAL_SCREEN and
SMG$RESTORE_PHYSICAL_SCREEN, the calls must be performed in a nested
order; that is, the last pasteboard saved must be the first one
restored, and so on.
These routines are useful when calling a procedure that may send output
to the screen without using the Screen Management Facility. Before
calling such a procedure, you save the pasteboard image with
SMG$SAVE_PHYSICAL_SCREEN. After the procedure executes, you restore the
pasteboard image with SMG$RESTORE_PHYSICAL_SCREEN.
Note that the saved region must encompass at least two rows. When you
use SMG$SAVE_PHYSICAL_SCREEN on a terminal that does not support
scrolling regions, you must save and restore the entire pasteboard.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVPAS_ID
|
Invalid
pasteboard-id.
|
|
SMG$_INVROW
|
Invalid row, or range specified does not encompass at least two rows.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
|
LIB$_INSVIRMEM
|
Insufficient virtual memory.
|
SMG$SAVE_VIRTUAL_DISPLAY
The Save the Virtual Display to a File routine saves the contents of a
virtual display and stores it in a file.
Format
SMG$SAVE_VIRTUAL_DISPLAY display-id [,filespec]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
display-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the virtual display to be saved. The
display-id argument is the address of an unsigned
longword that contains the display identifier.
The display identifier is returned by SMG$CREATE_VIRTUAL_DISPLAY.
filespec
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
String containing the file specification of the file in which the
specified virtual display is saved. The filespec
argument is the address of a descriptor pointing to the character
string containing the file specification.
A new file is created each time this routine is called. If
filespec is omitted, the default file specification is
SMGDISPLY.DAT.
Description
SMG$SAVE_VIRTUAL_DISPLAY saves the contents of a virtual display and
stores it in a nonprintable file. The text, renditions, and all
attributes necessary to reconstruct the virtual display are saved.
Menu, viewport, and subprocess context are not saved. The
SMG$LOAD_VIRTUAL_DISPLAY routine restores the virtual display.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
RMS$_
xxxx
|
Any error returned by $OPEN, $CONNECT, $PUT, $CLOSE.
|
|
