OpenVMS RTL Screen Management (SMG$) Manual

Document revision date: 30 March 2001

OpenVMS RTL Screen Management (SMG$) Manual

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

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

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.

Contents

Index

privacy and legal statement

5935PRO_014.HTML

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

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

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

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

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

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.

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.

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

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.

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.

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.