Document revision date: 30 March 2001

## OpenVMS RTL Screen Management (SMG$) Manual

Previous | Contents | Index

## SMG$DEFINE_KEY

> The Perform a DEFINE/KEY Command routine performs the DEFINE/KEY command you provide.

### Format

> SMG$DEFINE_KEY key-table-id ,command-string

### RETURNS

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

### Arguments

> #### key-table-id

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

> Identifies the key definition table for which the DEFINE/KEY command is to be performed. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.

> The key table identifier is returned by SMG$CREATE_KEY_TABLE.

> #### command-string

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

> String containing the DEFINE/KEY command to be performed. The command-string argument is the address of a descriptor pointing to the command to be performed.

> The valid qualifiers for the DEFINE/KEY command are as follows:

> - /TERMINATE
> - /NOECHO
> - /LOCK
> - /IF_STATE
> - /SET_STATE

> The following two restrictions apply to the DEFINE/KEY qualifiers:

> - If you use the /LOCK qualifier, you must also use the /SET_STATE qualifier.
> - If you use both the /SET_STATE and /TERMINATE qualifiers, you may not use /LOCK.

### Description

> SMG$DEFINE_KEY parses and performs a DEFINE/KEY command. It can be used by programs that accept DEFINE/KEY commands but do not parse the commands themselves.

> SMG$DEFINE_KEY calls CLI$DCL_PARSE to parse the command line and then makes the appropriate call to SMG$ADD_KEY_DEF. The original command is then restored with a call to CLI$DCL_PARSE. Use of this procedure requires that the image be run under the DCL command language interpreter (CLI).

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_WRONUMARG | Wrong number of arguments.

Any condition values returned by LIB$SCOPY_DXDX.

Any condition values returned by CLI$ routines.

Any condition values returned by SMG$ADD_KEY_DEF.

## SMG$DELETE_CHARS

> The Delete Characters routine deletes characters in a virtual display.

### Format

> SMG$DELETE_CHARS display-id ,number-of-characters ,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

> Identifies the virtual display from which characters are to be deleted. 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-characters

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

> Specifies the number of characters to be deleted. The number-of-characters argument is the address of a signed longword that contains the number of characters to be deleted.

> #### start-row

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

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

> #### start-column

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

> Specifies the column position at which to start the deletion. The start-column argument is the address of a signed longword that contains the column position at which to start the deletion.

### Description

> SMG$DELETE_CHARS deletes a specified number of characters, starting at a specified row and column position. Remaining characters on the line are shifted to the left to occupy the vacated spaces. Note that this routine deletes characters only on a single line.

> If you specify more characters than are available for deletion, SMG$DELETE_CHARS deletes all characters from the specified column position to the end of the line.

> This routine leaves the virtual cursor at the position of the first character deleted.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | Invalid argument. The number of characters specified extends outside the virtual display.
> SMG$_INVCOL | Invalid column position. The specified column is outside the virtual display.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVROW | Invalid row position. The specified row is outside the virtual display.
> SMG$_WILUSERMS | Pasteboard is not a video terminal.
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

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

            INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD
            INTEGER SMG$PASTE_VIRTUAL_DISPLAY,  SMG$PUT_CHARS
            INTEGER SMG$DELETE_CHARS, DISPLAY1, PASTE1
            INTEGER ROWS, COLUMNS, BORDER, STATUS
    C+
    C Create the virtual display be calling SMG$CREATE_VIRTUAL_DISPLAY.
    C To give it a border, set BORDER = 1. 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 Call SMG$CREATE_PASTEBOARD to create the pasteboard.
    C-

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

    C+
    C Use 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 to the pasteboard using
    C 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$DELETE_CHARS to delete 4 characters from row 4
    C starting from character (column) 14, removing the characters
    C "rder" from the word "bordered".
    C-

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

            END

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

> Figure SMG-10 Output Generated Before the Call to SMG$DELETE_CHARS

The output generated after the call to SMG$DELETE_CHARS is shown in Figure SMG-11.

Figure SMG-11 Output Generated After the Call to SMG$DELETE_CHARS

## SMG$DELETE_KEY_DEF

> The Delete Key Definition routine deletes a key definition from the specified table of key definitions.

### Format

> SMG$DELETE_KEY_DEF key-table-id ,key-name [,if-state]

### RETURNS

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

### Arguments

> #### key-table-id

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

> Identifies the key table from which the key definition is deleted. The key-table-id argument is the address of an unsigned longword that contains the key table identifier.

> #### key-name

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

> String containing the name of the key whose definition is to be deleted. The key-name argument is the address of a descriptor pointing to the key name. The key name is stripped of trailing blanks and converted to uppercase before use.

> Table 3-1 lists the valid key names.

> #### if-state

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

> String containing a state name that further qualifies key-name. The if-state argument is the address of a descriptor pointing to the state name. If omitted, the null state is used. Thus if a key has several definitions depending on various values of if-state, this routine lets you delete only one of those definitions.

### Description

> SMG$DELETE_KEY_DEF deletes a key definition from the specified table of key definitions.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVKEYNAM | Invalid key-name.
> SMG$_INVKTB_ID | Invalid key-table-id.
> SMG$_KEYDEFPRO | Key definition is protected.
> SMG$_KEYNOTDEF | Key is not defined.
> SMG$_WRONUMARG | Wrong number of arguments.

## SMG$DELETE_LINE

> The Delete Line routine deletes lines from a virtual display.

### Format

> SMG$DELETE_LINE display-id ,start-row [,number-of-rows]

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

> Identifies the virtual display from which lines are to be deleted. 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 first line to be deleted from the virtual display. The start-row argument is the address of a signed longword that contains the number of the first line to be deleted.

> #### number-of-rows

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

> Specifies the number of lines to be deleted. The number-of-rows argument is the address of a signed longword that contains the number of lines to be deleted. If omitted, one line is deleted.

### Description

> SMG$DELETE_LINE deletes one or more lines from a virtual display and scrolls the remaining lines up into the space created by the deletion. Blank lines fill the display on the bottom. The virtual cursor is left at the first column position in start-row.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVARG | Invalid argument.
> SMG$_INVDIS_ID | Invalid display-id.
> SMG$_INVROW | Invalid row.
> SMG$_WILUSERMS | Pasteboard is not a video terminal.
> SMG$_WRONUMARG | Wrong number of arguments.

### Example

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

            IMPLICIT INTEGER (A-Z)
    C+
    C Create the virtual display by calling SMG$CREATE_VIRTUAL_DISPLAY.
    C To give it a border, set BORDER = 1.  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 Call SMG$CREATE_PASTEBOARD to create the pasteboard.
    C-

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

    C+
    C Use 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 to the pasteboard using
    C 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$DELETE_LINE to delete rows 3, 4, and 5.
    C-

            STATUS = SMG$DELETE_LINE ( DISPLAY1, 3, 3)
            IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))

            END

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

> Figure SMG-12 Output Generated by Fortran Program Before the Call to SMG$DELETE_LINE

The output generated after the call to SMG$DELETE_LINE is shown in Figure SMG-13.

Figure SMG-13 Output Generated After the Call to SMG$DELETE_LINE

## SMG$DELETE_MENU

> The End Access to a Menu in the Virtual Display routine ends access to the menu choices in the specified virtual display.

### Format

> SMG$DELETE_MENU display-id [,flags]

### 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 in which the menu choices are displayed. The display-id argument is the address of an unsigned longword containing this identifier.

> #### flags

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

> Optional bit mask specifying possible actions to take when deleting the menu. The flags argument is the address of an unsigned longword that contains the flag. At this time, the only valid value is SMG$M_ERASE_MENU. If this option is specified, all rows containing menu items are erased.

### Description

> SMG$DELETE_MENU discontinues access to the menu choices in the specified virtual display. The optional flags argument lets you specify that the menu choices be removed from the display when the menu is deleted.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> LIB$_xxxx | Any condition value returned by LIB$FREE_VM.
> SMG$_xxxx | Any condition value returned by SMG$ERASE_DISPLAY.

## SMG$DELETE_PASTEBOARD

> The Delete Pasteboard routine deletes a pasteboard.

### Format

> SMG$DELETE_PASTEBOARD pasteboard-id [,flags]

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

> #### flags

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

> Optional bit mask specifying whether the screen is cleared after the specified pasteboard is deleted. The flags argument is the address of an unsigned longword that contains the flag. Valid values are as follows:

> 0 | Does not clear the screen.
> SMG$M_ERASE_PBD | Clears the screen (default).
> SMG$M_IGNORE_BATCHED | Deletes the pasteboard even if batching is in effect.

### Description

> SMG$DELETE_PASTEBOARD flushes all output to the display, terminates all use of the specified pasteboard, and deallocates all resources associated with the pasteboard.

### Condition Values Returned

> SS$_NORMAL | Normal successful completion.
> SMG$_INVPAS_ID | Invalid pasteboard-id.
> SMG$_NOTPASTED | The specified virtual display is not pasted to the specified pasteboard.
> SMG$_WILUSERMS | Pasteboard is not a video terminal.
> SMG$_WRONUMARG | Wrong number of arguments.

Any condition values returned by $DASSGN, LIB$FREE_VM, LIB$FREE_EF, or SMG$FLUSH_BUFFER.

Previous | Next | Contents | Index

| privacy and legal statement |
5935PRO_014.HTML