Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS RTL Screen Management (SMG$) Manual


Previous 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)' 
 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.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5935PRO_034.HTML