Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

## SMG$ERASE_COLUMN

> The Erase Column from Display routine erases the specified portion of the virtual display from the given position to the end of the column.

### Format

> SMG$ERASE_COLUMN display-id [,start-row] [,column-number] [,end-row]

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

> Identifier of the virtual display to be affected. The display-id argument is the address of an unsigned longword containing this virtual display identifier.

> #### start-row

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

> Optional line number at which the erase operation begins. The start-row argument is the address of a signed longword that contains the specified line number. If this argument is omitted, the column-number argument is ignored and the erase operation begins at the current location of the virtual cursor for that virtual display.

> #### column-number

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

> Optional column number at which the erase operation begins. The column-number argument is the address of a signed longword that contains the specified column number. If this argument is omitted, the start-row argument is ignored and the erase operation begins at the current location of the virtual cursor for that virtual display.

> #### end-row

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

> Optional row number at which the erase operation ends. The end-row argument is the address of a signed longword that contains the specified row number.

### Description

> SMG$ERASE_COLUMN lets you erase a column of the virtual display from the specified position to the end of the column. If the position is not specified, the erase operation begins at the current position of the virtual cursor in the specified virtual display. After the erase operation has completed, this routine leaves the virtual cursor at the position of the first character erased.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.

## SMG$ERASE_DISPLAY

> The Erase Virtual Display routine erases all or part of a virtual display by replacing text characters with blanks.

### Format

> SMG$ERASE_DISPLAY 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 to be erased. 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 the erase operation begins. The start-row argument is the address of a signed longword that contains the number of the row at which the erasure begins.

> If the start-row argument is not specified, start-column is also ignored and the entire virtual display is erased. If you do not specify start-row and start-column, then end-row and end-column are ignored and the entire virtual display is erased.

> #### start-column

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

> Specifies the column at which the erase operation begins. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure begins.

> If the start-column argument is not specified, start-row is also ignored and the entire virtual display is erased. If you do not specify start-row and start-column, then end-row and end-column are ignored and the entire virtual display is erased.

> #### end-row

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

> Specifies the row at which the erase operation ends; that is, the last row to be erased. The end-row argument is the address of a signed longword that contains the number of the last row to be erased.

> If the end-row argument is not specified, end-column is also ignored and all remaining rows in the display are erased.

> #### end-column

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

> Specifies the column at which the erase operation ends; that is, the last column to be erased. The end-column argument is the address of a signed longword that contains the number of the last column to be erased.

> If the end-column argument is not specified, end-row is also ignored and all remaining columns in the display are erased.

### Description

> SMG$ERASE_DISPLAY causes all or part of a virtual display to be erased by replacing text characters with blanks. If omitted, the starting positions default to 1,1. The ending positions default to the last row or column in the display. Thus, to erase the entire virtual display, you need only pass the display-id. This routine leaves the virtual cursor at the start of the erased position. If the entire display is erased, the virtual cursor is left at position 1,1.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVCOL | Invalid column number. The specified column is outside the virtual display.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVROW | Invalid row number. The specified row is outside the virtual display.
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

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

            IMPLICIT INTEGER (A-Z)

    C+
    C Call SMG$CREATE_VIRTUAL_DISPLAY to create the virtual
    C display. To give it a border, set BORDER = 1.
    C No border would be BORDER = 0.
    C-

            ROWS = 7
            COLUMNS = 50
            BORDER = 1

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

    C+
    C Using SMG$CREATE_PASTEBOARD, create the pasteboard.
    C-

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

    C+
    C Call SMG$PUT_CHARS to put data in the virtual display.
    C-
            STATUS = SMG$PUT_CHARS ( DISPLAY1,
         1        ' This virtual display has 7 rows and 50 columns.', 2, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

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

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

    C+
    C Paste the virtual display by calling SMG$PASTE_VIRTUAL_DISPLAY.
    C-

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

    C+
    C Call SMG$ERASE_DISPLAY to erase the display from row 2,
    C column 6, through row 4, column 28.
    C-

            STATUS = SMG$ERASE_DISPLAY ( DISPLAY1, 2, 6, 4, 28)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            END

> The initial display output by this Fortran program is shown in Figure SMG-22.

> Figure SMG-22 Initial Output of Fortran Program Calling SMG$ERASE_DISPLAY

This output displayed after the call to SMG$ERASE_DISPLAY is shown in Figure SMG-23.

Figure SMG-23 Output Displayed After the Call to SMG$ERASE_DISPLAY

## SMG$ERASE_LINE

> The Erase Line routine erases all or part of a line in a virtual display.

### Format

> SMG$ERASE_LINE 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 to be affected. 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 line at which the erase operation starts. The start-row argument is the address of a signed longword that contains the number of the row at which the erasure starts. If omitted, start-column is also ignored and the current cursor position is used.

> #### start-column

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

> Specifies the column at which the erase operation starts. The start-column argument is the address of a signed longword that contains the number of the column at which the erasure starts. If omitted, start-row is also ignored and the current cursor position is used.

### Description

> SMG$ERASE_LINE erases a line from the specified starting position to the end of the line. If you do not specify a starting position, SMG$ERASE_LINE erases text from the current virtual cursor position to the end of the line. This routine leaves the virtual cursor at the start of the erased portion.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVCOL | Invalid column number. The specified column is outside the virtual display.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVROW | Invalid row number. The specified row is outside the virtual display.
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

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

            IMPLICIT INTEGER (A-Z)
            INCLUDE '($SMGDEF)'

    C+
    C Use SMG$CREATE_VIRTUAL_DISPLAY to create a virtual display
    C with a border.
    C-

            ROWS = 7
            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 by calling SMG$PUT_CHARS.
    C-

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

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

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

    C+
    C Use 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 Call SMG$ERASE_LINE to erase line 2, and then again to
    C erase the last 4 words on line 4.
    C-

            STATUS = SMG$ERASE_LINE ( DISPLAY1, 2, 1)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            STATUS = SMG$ERASE_LINE ( DISPLAY1, 4, 9)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            END

> The initial output generated by the Fortran program is shown in Figure SMG-24.

> Figure SMG-24 Initial Output Generated by Fortran Program Calling SMG$ERASE_LINE

The output generated after the call to SMG$ERASE_LINE is shown in Figure SMG-25.

Figure SMG-25 Output Generated After the Call to SMG$ERASE_LINE

## SMG$ERASE_PASTEBOARD

> The Erase Pasteboard routine erases the contents of a pasteboard.

### Format

> SMG$ERASE_PASTEBOARD 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 erased. The pasteboard-id argument is the address of an unsigned longword that contains the pasteboard identifier.

> The pasteboard identifier is returned by SMG$CREATE_PASTEBOARD.

### Description

> SMG$ERASE_PASTEBOARD erases the contents of a specified pasteboard. The physical cursor is left at position 1,1. If there are any virtual displays pasted to the pasteboard, they will be redrawn the next time the Screen Management Facility is used to output to the pasteboard.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SS$_xxxx | Any status from $QIOW.
> SMG$_BATWAS_ON | Pasteboard is batched.
> 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$ERASE_PASTEBOARD.
    C-

            IMPLICIT INTEGER*4 (A-Z)
            CHARACTER*80    OUT_STR,TRIM_STR
            CHARACTER*18    PROMPT          /'Please enter data '/

            SMG$M_BOLD = 1
            SMG$M_REVERSE = 2
            SMG$M_BLINK = 4
            SMG$M_UNDERLINE = 8
    C+
    C Establish the terminal screen as a pasteboard using
    C SMG$CREATE_PASTEBOARD.
    C-

            STATUS = SMG$CREATE_PASTEBOARD (NEW_PID,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Establish the terminal keyboard as the virtual keyboard
    C by calling SMG$CREATE_VIRTUAL_KEYBOARD.
    C-

            STATUS = SMG$CREATE_VIRTUAL_KEYBOARD(KEYBOARD_ID,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Establish a virtual display region by
    C calling SMG$CREATE_VIRTUAL_DISPLAY.
    C-

            STATUS = SMG$CREATE_VIRTUAL_DISPLAY (5,80,DISPLAY_ID,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Paste the virtual display to the screen, starting at
    C row 10, column 15.  To paste the virtual display, use
    C SMG$PASTE_VIRTUAL_DISPLAY.
    C-

            STATUS = SMG$PASTE_VIRTUAL_DISPLAY(DISPLAY_ID,NEW_PID,10,15)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Prompt the user for input, and accept that input using
    C SMG$READ_STRING.
    C-

            STATUS = SMG$READ_STRING(KEYBOARD_ID,OUT_STR,PROMPT,,,,,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Clear the screen using SMG$ERASE_PASTEBOARD.
    C-

            STATUS = SMG$ERASE_PASTEBOARD (NEW_PID)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
    C+
    C Trim any trailing blanks from the user input
    C by calling STR$TRIM.
    C-
            STATUS = STR$TRIM(TRIM_STR,OUT_STR,STR_LEN)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

    C+
    C Display the data input by the user using SMG$PUT_CHARS
    C and SMG$PUT_LINE.
    C-

            STATUS = SMG$PUT_CHARS(DISPLAY_ID,'You entered: ',,,,,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
            STATUS = SMG$PUT_LINE(DISPLAY_ID,TRIM_STR(1:STR_LEN),,
         1                               SMG$M_REVERSE,0,,)
            IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
            END

> This Fortran program calls Run-Time Library Screen Management routines to format screen output, and to accept and display user input.

## SMG$EXECUTE_COMMAND

> The Execute Command in a Subprocess routine executes the specified command in the subprocess created with the SMG$CREATE_SUBPROCESS routine.

### Format

> SMG$EXECUTE_COMMAND display-id ,command-desc [,flags] [,ret-status]

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

> Display identifier of the virtual display with which the subprocess is associated. The display-id argument is the address of an unsigned longword containing this identifier.

> #### command-desc

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

> Command string. The command-desc argument is the address of a descriptor pointing to the command string.

> #### flags

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

> Optional bit mask that specifies optional behavior. The flags argument is the address of an unsigned longword that contains the flag. The valid values for flags are as follows:

> SMG$M_DATA_FOLLOWS | Input data follows. The next call to SMG$EXECUTE_COMMAND contains input data for the currently executing command. Do not specify this value if this is the last input data item. If you do specify this value, ret-status is not returned.
> SMG$M_SEND_EOF | Send end-of-file marker. The end-of-file marker is sent to the subprocess.

> #### ret-status

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

> Optional status of the executed command, provided that the commands are not being buffered. The ret-status argument is the address of an unsigned longword containing this status.

### Description

> SMG$EXECUTE_COMMAND lets you execute the specified command in the subprocess created with SMG$CREATE_SUBPROCESS. If commands are being buffered, this routine returns control after the command has been buffered, and the user-specified AST routine is invoked when the command completes. If commands are not being buffered, SMG$EXECUTE_COMMAND waits until the command has completed execution before returning the status of the command.

> When specifying the command string, you must specify a dollar sign ($) as the first character of any DCL command. Any command string that does not begin with a dollar sign is assumed to be input data for the previous command. SMG$EXECUTE_COMMAND outputs the commands and their output to the specified virtual display as they are executed. Do not perform I/O to the specified virtual display. Note that the commands SPAWN, GOTO, and LOGOUT are illegal to use as command strings and generate unpredictable results.

> Since I/O is performed using mailboxes and not through the terminal driver, command prompts and single-character commands such as Ctrl/C, Ctrl/Y, Ctrl/Z, and so forth have no effect. You should specify SMG$M_SEND_EOF for the flags argument in order to send a Ctrl/Z to the subprocess. For more information on mailboxes, see the mailbox driver section of the OpenVMS I/O User's Reference Manual.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SS$_xxxx | Any status from $QIO, $DCLAST, or $SYNCH.
> SMG$_INPTOOLON | Input is longer than 255 characters.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_NOSUBEXI | No subprocess exists.
> SMG$_xxxx | Any status from SMG$PUT_LINE.
> LIB$_xxxx | Any status from LIB$ANALYZE_SDESC.

Previous | Next | Contents | Index

| privacy and legal statement |
5935PRO_018.HTML