OpenVMS RTL Screen Management (SMG$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Screen Management (SMG$) Manual

Contents

Index

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)' CHARACTER20 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

!+ 
! 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.

Contents

Index

privacy and legal statement

5935PRO_034.HTML

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	identifier
type:	longword (unsigned)
access:	read only
mechanism:	by reference

SS$_NORMAL	Normal successful completion.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVPAS_ID	Invalid pasteboard-id.

OpenVMS usage:	longword_signed
type:	longword (signed)
access:	write only
mechanism:	by reference

OpenVMS usage:	char_string
type:	character string
access:	write only
mechanism:	by descriptor

OpenVMS usage:	byte_unsigned
type:	byte (unsigned)
access:	read only
mechanism:	by reference

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

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.