Document revision date: 30 March 2001

## 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

| privacy and legal statement |
5935PRO_034.HTML