Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

## SMG$REMOVE_LINE

> The Remove a Line from a Virtual Display routine removes a line from a specified virtual display that was drawn with the SMG$DRAW_LINE or SMG$DRAW_RECTANGLE routines.

### Format

> SMG$REMOVE_LINE display-id ,start-row ,start-column ,end-row ,end-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 from which the line is to be removed. 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: | read only
> mechanism: | by reference

> Specifies the row at which to begin removing the line. The start-row argument is the address of a signed longword that contains the row number.

> #### start-column

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Specifies the column at which to begin removing the line. The start-column argument is the address of a signed longword that contains the column number.

> #### end-row

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Specifies the row at which the line to be removed ends. The end-row argument is the address of a signed longword that contains the row number.

> #### end-column

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Specifies the column at which the line to be removed ends. The end-column argument is the address of a signed longword that contains the column number.

### Description

> SMG$REMOVE_LINE removes a line drawn with SMG$DRAW_LINE or SMG$DRAW_RECTANGLE from a specified starting row and column to a specified ending row and column.

> This routine erases the line you specify but preserves the line-drawing characters at any line intersection. The line-drawing characters are the terminal's line-drawing character set. If that is not available, the plus sign (+), minus sign (-), and vertical bar (|) characters are used.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_DIALINNOT | Diagonal line not allowed.
> SMG$_INVCOL | Invalid column number. The specified column is outside the virtual display.
> SMG$_INVROW | Invalid row number. The specified row is outside the virtual display.
> SMG$_WRONUMARG | Wrong number of arguments.

## SMG$REPAINT_LINE

> The Repaint One or More Lines on the Current Pasteboard routine repaints a series of lines on the current pasteboard.

### Format

> SMG$REPAINT_LINE pasteboard-id ,start-row [,number-of-lines]

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

> Pasteboard identifier. The pasteboard-id argument is the address of the pasteboard associated with the physical screen to be repainted.

> #### start-row

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Starting row number. The start-row argument is the address of the pasteboard row number to start repainting.

> #### number-of-lines

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Number of contiguous lines to repaint. The number-of-lines argument is the address of a signed longword containing the number of lines. This argument is optional. If not specified, the default is 1.

### Description

> SMG$REPAINT_LINE repaints a line or series of lines on the specified pasteboard based on its memory of what the pasteboard should look like. You should call SMG$REPAINT_LINE when you suspect that the pasteboard has been disrupted.

> SMG$REPAINT_LINE has the added benefit of circumventing the restriction that the display you are working on must be pasted to column 1. (For further information on this restriction, refer to the description section of SMG$READ_STRING.

> This routine should not be used if the line being repainted is double height.

> One good use of SMG$REPAINT_LINE is to restore a line after entering a Ctrl/U or Ctrl/R to an input routine.

### Condition Values Signaled

> SS$NORMAL | Normal successful completion.
> SMG$_INVPAS_ID | Invalid pasteboard-id.

## SMG$REPAINT_SCREEN

> The Repaint Current Pasteboard routine repaints the specified pasteboard after non-SMG$ I/O has occurred.

### Format

> SMG$REPAINT_SCREEN pasteboard-id

### RETURNS

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

### Argument

> #### pasteboard-id

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

> Specifies the pasteboard to be repainted. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

### Description

> SMG$REPAINT_SCREEN repaints the specified pasteboard. It is intended to be used when some outside agent (for example, a broadcast message) has disrupted the pasteboard.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVPAS_ID | Invalid pasteboard-id.
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

    C+
    C This Fortran example program demonstrates
    C the use of SMG$REPAINT_SCREEN.
    C-

            IMPLICIT INTEGER (A-Z)

    C+
    C Create the virtual display by calling
    C SMG$CREATE_VIRTUAL_DISPLAY. To create
    C a border, we set BORDER = 1. No border
    C would be BORDER = 0.
    C-
            INCLUDE '($SMGDEF)'
            ROWS = 3
            COLUMNS = 50
            BORDER = 1

            STATUS = SMG$CREATE_VIRTUAL_DISPLAY
         1          (ROWS, COLUMNS, DISPLAY1, 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 Put data in the virtual display by calling SMG$PUT_CHARS.
    C-

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1       ' This virtual display has 3 rows and 50 columns.', 1, 1 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1       ' This is a bordered virtual display.', 2, 1 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1       ' SMG$PUT_CHARS puts data in this virtual display.', 3, 1 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display.
    C-

            STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Mess up the screen with some FORTRAN output.
    C-

            WRITE (6,*) 'Mess up the screen.'
            WRITE (6,*) 'More mess.'

    C+
    C Call SMG$REPAINT_SCREEN to repaint the screen.
    C-

            STATUS = SMG$REPAINT_SCREEN ( PASTE1 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            END

> The output generated by this Fortran program before the call to SMG$REPAINT_SCREEN is shown in Figure SMG-40.

> Figure SMG-40 Output Generated by Fortran Program Calling SMG$REPAINT_SCREEN

The output generated after the call to SMG$REPAINT_SCREEN is shown in Figure SMG-41.

Figure SMG-41 Output Generated by Fortran Program Calling SMG$REPAINT_SCREEN

## SMG$REPASTE_VIRTUAL_DISPLAY

> The Repaste Virtual Display routine moves a virtual display to a new position on the pasteboard. The pasting order is not preserved.

### Format

> SMG$REPASTE_VIRTUAL_DISPLAY display-id ,pasteboard-id ,pasteboard-row ,pasteboard-column [,top-display-id]

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

> #### pasteboard-id

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

> Specifies the pasteboard on which the display is repasted. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

> #### pasteboard-row

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Specifies the pasteboard row that is to contain row 1 of the specified virtual display. The pasteboard-row argument is the address of a signed longword that contains the pasteboard row.

> #### pasteboard-column

> OpenVMS usage: | longword_signed
> type: | longword (signed)
> access: | read only
> mechanism: | by reference

> Specifies the pasteboard column that is to contain column 1 of the specified virtual display. The pasteboard-column argument is the address of a signed longword that contains the pasteboard column.

> #### top-display-id

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

> Optional identifier of the virtual display under which display-id will be pasted. The top-display-id argument is the address of an unsigned longword containing the identifier of this virtual display. Note that the virtual display specified by top-display-id must already be pasted.

### Description

> SMG$REPASTE_VIRTUAL_DISPLAY lets you move a virtual display to a new position on its pasteboard. This routine calls SMG$UNPASTE_VIRTUAL_DISPLAY and SMG$PASTE_VIRTUAL_DISPLAY. Note that this changes the pasting order. The unpasting and repasting operations use the SMG$BEGIN_PASTEBOARD_UPDATE and SMG$END_PASTEBOARD_UPDATE routines; thus, there is no effect on the screen until the repasting operation is complete.

> Note that this routine may cause the virtual display to be at the top of the pasting order. To move a virtual display without changing its pasting order, use SMG$MOVE_VIRTUAL_DISPLAY. If the optional argument top-display-id is specified, SMG$REPASTE_VIRTUAL_DISPLAY pastes the virtual display being repasted under the virtual display specified by top-display-id. In this case, the virtual display specified by top-display-id must already be pasted.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVPAS_ID | Invalid pasteboard-id.
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

    C+
    C This Fortran example program demonstrates the use of
    C SMG$REPASTE_VIRTUAL_DISPLAY and SMG$MOVE_VIRTUAL_DISPLAY.
    C-

            IMPLICIT INTEGER (A-Z)

    C+
    C Include the SMG definitions. In particular, we want SMG$M_BORDER.
    C-

            INCLUDE '($SMGDEF)'

    C+
    C Create a virtual display with a border by calling
    C SMG$CREATE_VIRTUAL_DISPLAY.
    C-

            ROWS = 3
            COLUMNS = 50

            STATUS = SMG$CREATE_VIRTUAL_DISPLAY
         1          (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
    C-

            STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Put data in the virtual display using SMG$PUT_CHARS.
    C-

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1       ' This virtual display has 3 rows and 50 columns.', 1, 1 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1       ' This is a bordered virtual display.', 2, 1 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1       ' SMG$PUT_CHARS puts data in this virtual display.', 3, 1 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Call SMG$PASTE_VIRTUAL_DISPLAY to paste the virtual display.
    C-

            STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Move the virtual display by calling SMG$MOVE_VIRTUAL_DISPLAY.
    C-

            STATUS = SMG$MOVE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 10, 5 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

    C+
    C Call SMG$REPASTE_VIRTUAL_DISPLAY to repaste the
    C original virtual display as it was.
    C-

            STATUS = SMG$REPASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 15 )
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            END

> The output generated by this Fortran program before the call to SMG$MOVE_VIRTUAL_DISPLAY is shown in Figure SMG-42.

> Figure SMG-42 Output Before the Call to SMG$MOVE_VIRTUAL_DISPLAY

After the call to SMG$MOVE_VIRTUAL_DISPLAY, the output is that shown in Figure SMG-43.

Figure SMG-43 Output Displayed After the Call to SMG$MOVE_VIRTUAL_DISPLAY

Figure SMG-44 shows the final output displayed after the call to SMG$REPASTE_VIRTUAL_DISPLAY.

Figure SMG-44 Output Displayed After the Call to SMG$REPASTE_VIRTUAL_DISPLAY

## SMG$REPLACE_INPUT_LINE

> The Replace Input Line routine replaces the specified lines in the recall buffer with the specified string.

### Format

> SMG$REPLACE_INPUT_LINE keyboard-id [,replace-string] [,line-count] [,flags]

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

> You create a virtual keyboard by calling the SMG$CREATE_VIRTUAL_KEYBOARD routine.

> #### replace-string

> OpenVMS usage: | char_string
> type: | character string
> access: | read only
> mechanism: | by descriptor

> String that contains the line to be entered into the recall buffer. The replace-string argument is the address of a descriptor pointing to this string. The default is a null string, which removes the last line entered.

> #### line-count

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

> Number of lines to be replaced. The line-count argument is the address of an unsigned byte containing the number of lines to be replaced with replace-string. The default value for the line-count argument is 1 (the last line entered).

> #### flags

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by reference

> Specifies optional behavior. The flags argument is the address of an unsigned longword that contains the flag. There is one valid value:

> SMG$M_KEEP_CONTENTS | The string specified by replace-string replaces the existing string specified by line-count. By using this flag in a loop, the line recall buffer can be preloaded with information by the application.

### Description

> SMG$REPLACE_INPUT_LINE replaces the requested lines in the recall buffer with the specified string. The remaining (line-count - 1 ) lines are deleted. This routine aids in processing line continuations.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVKBD_ID | Invalid keyboard-id.
> SMG$_WRONUMARG | Wrong number of arguments.
> LIB$_INSVIRMEM | Insufficient virtual memory.

### Example

    !+
    ! This FORTRAN example uses the routine
    ! SMG$REPLACE_INPUT_LINE to concatenate
    ! the last two lines in the recall buffer.
    !-

     IMPLICIT INTEGER (A-Z)
     INCLUDE '($SMGDEF)'
     INCLUDE '($SMGMSG)'
     CHARACTER*20 TEXT, TEXT1

     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

    !+
    ! Recall last two lines in the buffer.
    !-

     S = SMG$RETURN_INPUT_LINE(KBID,TEXT,,1,LEN)
     IF (.NOT. S) CALL LIB$STOP(%VAL(S))
     S = SMG$RETURN_INPUT_LINE(KBID,TEXT1,,2,LEN1)
     IF (.NOT. S) CALL LIB$STOP(%VAL(S))
     TEXT(LEN:20) = TEXT1(1:LEN1)

    !+
    ! Concatenate them and replace the last two
    ! lines in the buffer with the new line.
    !-

     S = SMG$REPLACE_INPUT_LINE(KBID,TEXT,2)
     IF (.NOT. S) CALL LIB$STOP(%VAL(S))

    !+
    ! Recall the last line which is now the
    ! concatenated line.
    !-

     S = SMG$RETURN_INPUT_LINE(KBID,TEXT,,1)
     IF (.NOT. S) CALL LIB$STOP(%VAL(S))

     S = SMG$PUT_LINE(DID,'**** The last line of text is:')
     IF (.NOT. S) CALL LIB$STOP(%VAL(S))
     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 REPLACE
>     Enter number of lines to save.
>       3
>     Enter lines of text:
>     Example> PASTEBOARD
>     Example> DISPLAY
>     Example> KEYBOARD
>     ****The last line of text is:
>     KEYBOARDDISPLAY

Previous | Next | Contents | Index

| privacy and legal statement |
5935PRO_033.HTML