Document revision date: 30 March 2001

The Return Pasting Information routine returns the pasteboard identifier of the pasteboard to which the specified virtual display is pasted. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual display are also returned.

Format

SMG$LIST_PASTEBOARD_ORDER display-id ,context ,pasteboard-id [,pasteboard-row] [,pasteboard-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

Display identifier of the virtual display that is pasted. The display-id argument is the address of an unsigned longword containing the identifier of this display.

context

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Context to search. The context argument is the address of an unsigned longword containing this context. On the initial call, you should set context to zero. SMG$LIST_PASTEBOARD_ORDER updates the value of context. The updated value should then be passed on the subsequent calls to obtain the next pasted display identifier.

pasteboard-id

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

Receives the identifier of the pasteboard on which the virtual display is pasted. The pasteboard-id argument is the address of an unsigned longword containing the identifier of this pasteboard.

pasteboard-row

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

Row of the pasteboard that contains row 1 of the specified virtual display. The optional pasteboard-row argument is the address of a signed longword containing the number of the pasteboard row that contains the first row of the virtual display.

pasteboard-column

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

Column of the pasteboard that contains column 1 of the specified virtual display. The optional pasteboard-column argument is the address of a signed longword containing the number of the pasteboard column that contains the first column of the virtual display.

Description

SMG$LIST_PASTEBOARD_ORDER returns the pasteboard identifier of the pasteboard to which the specified virtual display is pasted. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual displays are also returned.

SMG$LIST_PASTEBOARD_ORDER returns the identifier of the first (or bottom-most) pasteboard to which the specified virtual display is pasted. Call this routine in a loop, once for each succeeding pasteboard, until SMG$_NOPASTED is returned.

This routine is useful if, for example, you pasted a display to many pasteboards and you no longer know the pasteboard identifier of a pasteboard critical to your application.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_NOPASTED	No more displays are pasted.
SMG$_WRONUMARG	Wrong number of arguments.

The Return Virtual Display Pasting Information routine returns the identifiers of the virtual displays pasted to a specified pasteboard. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual displays are also returned.

Format

SMG$LIST_PASTING_ORDER pasteboard-id ,context ,display-id [,pasteboard-row] [,pasteboard-column]

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

Identifier of the pasteboard on which the virtual display is pasted. The pasteboard-id argument is the address of an unsigned longword containing the identifier of this pasteboard.

context

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Context to search. The context argument is the address of an unsigned longword containing this context. On the initial call, you should set context to zero. SMG$LIST_PASTING_ORDER updates the value of context. The updated value should then be passed on subsequent calls to obtain the next pasted display identifier.

display-id

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

Identifier of the virtual display that is pasted. The display-id argument is the address of an unsigned longword containing the identifier of this virtual display.

pasteboard-row

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

Row of the pasteboard that contains row 1 of the specified virtual display. The optional pasteboard-row argument is the address of a signed longword containing the number of the pasteboard row that contains the first row of the virtual display.

pasteboard-column

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

Column of the pasteboard that contains column 1 of the specified virtual display. The optional pasteboard-column argument is the address of a signed longword containing the number of the pasteboard column that contains the first column of the virtual display.

Description

SMG$LIST_PASTING_ORDER returns the identifiers of the virtual displays pasted to a specified pasteboard. Optionally, the pasteboard row 1 and column 1 (origins) of the virtual displays are also returned.

SMG$LIST_PASTING_ORDER returns the identifier of the first (or bottommost) virtual display pasted. Call this routine in a loop, once for each succeeding pasted virtual display, until SMG$_NOTPASTED is returned.

This routine is useful if, for example, you created many virtual displays and you no longer know the display identifier of a virtual display critical to your application.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVPAS_ID	Invalid pasteboard-id.
SMG$_NOTPASTED	No more displays are pasted.
SMG$_WRONUMARG	Wrong number of arguments.

The Load Key Definitions routine loads a file of key definitions (DEFINE/KEY commands) into a specified key table.

Format

SMG$LOAD_KEY_DEFS key-table-id ,filespec [,default-filespec] [,flags]

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

Specifies the key table into which you are loading key definitions. 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.

filespec

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

String containing the file specification for the file of DEFINE/KEY commands. The filespec argument is the address of a descriptor pointing to the file specification.

default-filespec

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

String containing the default file specification for the file of DEFINE/KEY commands. The default-filespec argument is the address of a descriptor pointing to the default file specification. If omitted, the null string is used.

flags

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

Optional bit mask that specifies whether filespec is to be treated as a logical name. The flags argument is the address of an unsigned longword that contains the flag. If set, flags specifies that filespec should be translated, but if this is not possible, that the null string be used.

Description

SMG$LOAD_KEY_DEFS opens and reads a file containing DEFINE/KEY commands and calls SMG$DEFINE_KEY for each command line in the file. Use of SMG$LOAD_KEY_DEFS requires that the calling program be run under the DCL command language interpreter (CLI). This routine signals any errors encountered while processing command lines. For more information, see SMG$DEFINE_KEY.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_FILTOOLON	File specification is too long (over 255 characters).

Any condition values returned by SMG$DEFINE_KEY or $OPEN.

The Load a Virtual Display from a File routine creates a new virtual display and loads it with a virtual display saved with SMG$SAVE_VIRTUAL_DISPLAY.

Format

SMG$LOAD_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:	write only
mechanism:	by reference

Identifier of the new virtual display to be loaded with the saved virtual display. The display-id argument is the address of an unsigned longword into which is written the new display identifier.

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 a character string containing the file specification.

If filespec is omitted, SMG$LOAD_VIRTUAL_DISPLAY searches for the default file specification SMGDISPLY.DAT.

Description

SMG$LOAD_VIRTUAL_DISPLAY creates a new virtual display and loads it with a virtual display saved with SMG$SAVE_VIRTUAL_DISPLAY. The new virtual display contains text, renditions, and attributes from the saved virtual display, but does not include menu, viewport, and subprocess context. The new virtual display is not pasted to any pasteboard.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_ xxxx	Any condition value returned by SMG$CREATE_VIRTUAL_DISPLAY.
RMS$_ xxxx	Any error returned by $OPEN, $CONNECT, $PUT, and $CLOSE.

The Move Text from One Virtual Display to Another routine moves a rectangle of text from one virtual display to another virtual display. Given two points in opposite corners of the rectangle, SMG$MOVE_TEXT determines the desired width and height of the new virtual display.

Format

SMG$MOVE_TEXT display-id ,top-left-row ,top-left-column ,bottom-right-row ,bottom-right-column ,display-id2 [,top-left-row2] [,top-left-column2] [,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

Specifies the virtual display from which text is to be moved. 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.

top-left-row

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

Top left row of the rectangle of text you want to move. The top-left-row argument is the address of an unsigned longword containing the row number.

top-left-column

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

Top left column of the rectangle of text you want to move. The top-left-column argument is the address of an unsigned longword containing the column number.

bottom-right-row

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

Bottom right row of the rectangle of text you want to move. The bottom-right-row argument is the address of an unsigned longword containing the row number.

bottom-right-column

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

Bottom right column of the rectangle of text you want to move. The bottom-right-column argument is the address of an unsigned longword containing the column number.

display-id2

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

Specifies the virtual display to which the text is to be moved. The display-id2 argument is the address of an unsigned longword that contains the display identifier.

The display identifier display-id2 is returned by SMG$CREATE_VIRTUAL_DISPLAY.

top-left-row2

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

Top left row of the rectangle that is the destination of the text you want to move. The optional top-left-row2 argument is the address of an unsigned longword containing the row number. If you do not specify a value for top-left-row2, the text is moved to the current virtual cursor row.

top-left-column2

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

Top left column of the rectangle that is the destination of the text you want to move. The optional top-left-column2 argument is the address of an unsigned longword containing the column number. If you do not specify a value for top-left-column2, the text is moved to the current virtual cursor column.

flags

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

Optional bit mask that specifies the action to take when moving the specified text. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values:

SMG$M_TEXT_SAVE	Does not erase the text after moving.
SMG$M_TEXT_ONLY	Moves the text but not the attributes.

Description

SMG$MOVE_TEXT moves a rectangle of text from one virtual display to another virtual display. You specify the rectangle you want to move with the top-left-row, top-left-column, bottom-right-row, and bottom-right-column arguments, as shown in Figure SMG-32. The virtual cursor positions are not changed.

Figure SMG-32 Arguments for Moving Text

The rectangle of text is moved to the current virtual cursor row and column of the destination virtual display. To move the text to a different position, use the optional top-left-row2 and top-left-column2 arguments.

By default, the attributes of the first virtual display are moved and, after the rectangle of text is moved, it is erased from the first virtual display. You can use the flags argument to change those default values.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVCOL	Invalid column number.
SMG$_INVDIS_ID	Invalid display-id.
SMG$_INVROW	Invalid row number.
SMG$_WRONUMARG	Wrong number of arguments.

	privacy and legal statement
5935PRO_024.HTML