Updated: 11 December 1998

OpenVMS RTL Screen Management (SMG$) Manual

The Find Display that Contains the Cursor routine returns the identifier of the most recently pasted virtual display that contains the physical cursor.

Format

SMG$FIND_CURSOR_DISPLAY pasteboard-id ,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

Specifies the pasteboard in which the physical cursor is to be found. 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.

display-id

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

Receives the identifier of the display in which the physical cursor was found. The display-id argument is the address of an unsigned longword into which the display identifier is written.

pasteboard-row

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

The row position at which to begin the search for the physical cursor. The optional pasteboard-row argument is the address of a signed longword containing the pasteboard row. You can use pasteboard-row instead of the physical cursor row.

pasteboard-column

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

The column position at which to begin the search for the physical cursor. The optional pasteboard-column argument is the address of a signed longword containing the pasteboard column. You can use pasteboard-column instead of the physical cursor column.

Description

SMG$FIND_CURSOR_DISPLAY determines which virtual display contains the physical cursor on a specified pasteboard, and returns the virtual display's identifier. SMG$FIND_CURSOR_DISPLAY returns the display-id of the most recently pasted virtual display that contains the physical cursor. If no virtual display contains the physical cursor, this routine returns a zero, which is an invalid display identifier.

Condition Values Returned

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

The Flush Buffer routine flushes all buffered output to the terminal.

Format

SMG$FLUSH_BUFFER 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 flushed. 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$FLUSH_BUFFER causes all buffered output that is not already output to be sent to the pasteboard immediately. The Screen Management Facility outputs the text when the buffer is full; therefore, this routine is only needed when a partial buffer must be output. The calling program would normally call this routine just before performing some CPU-intensive calculations, or whenever the pasteboard must be up to date.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SS$_xxxx	Any error from $QIOW.
SMG$_INVPAS_ID	Invalid pasteboard-id.
SMG$_WRONUMARG	Wrong number of arguments.

The Flush Display Update routine flushes any update batching to the screen and leaves the update batching in effect.

Format

SMG$FLUSH_DISPLAY_UPDATE display-id

RETURNS

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

Argument

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 argument is returned by SMG$CREATE_VIRTUAL_DISPLAY.

Description

SMG$FLUSH_DISPLAY_UPDATE works with SMG$END_DISPLAY_UPDATE and SMG$BEGIN_DISPLAY_UPDATE to control the batching of output operations on a given virtual display. Each call to SMG$FLUSH_DISPLAY_UPDATE immediately updates the virtual display with all operations previously performed under batching, and written to the pasteboard if the virtual display is pasted.

SMG$FLUSH_DISPLAY_UPDATE can be used in place of a call to SMG$END_DISPLAY_UPDATE that is immediately followed by a call to SMG$BEGIN_DISPLAY_UPDATE, when the batch count is zero, with much better performance than the two calls.

Condition Values Returned

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

The Get Broadcast Message routine determines whether a message has been broadcast to the pasteboard and returns the message.

Format

SMG$GET_BROADCAST_MESSAGE pasteboard-id [,message] [,message-length] [,message-type]

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 checked for the presence of a broadcast message. 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.

message

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

A string that receives the broadcast message, if such a message is available. The message argument is the address of a descriptor that points to the string into which the message text is written. If this argument is omitted, the broadcast message is discarded.

message-length

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Receives the actual length of the broadcast message. The message-length argument is the address of an unsigned word into which is written the length of the message.

message-type

OpenVMS usage:	word_unsigned
type:	word (unsigned)
access:	write only
mechanism:	by reference

Receives the type of broadcast message. The message-type argument is the address of an unsigned word into which is written the type of message. Values for message-type are defined by the $MSGDEF library definition. If the value for message-type is not MSG$_TRMBRDCST, the condition value returned is SMG$_NOBRDMSG.

Description

SMG$GET_BROADCAST_MESSAGE determines if any broadcast messages have been sent to the specified pasteboard while broadcast trapping was enabled and, if so, returns the message in the message argument. You may call this routine repeatedly until all broadcast messages have been returned. If there are no more broadcast messages available, SMG$GET_BROADCAST_MESSAGE returns the success status SMG$_NO_MORMSG.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SMG$_INVPAS_ID	Invalid pasteboard-id.
SMG$_NO_MORMSG	Successful completion. No more messages to be returned.
SMG$_NONBRDMSG	Nonbroadcast message returned.
SMG$_WRONUMARG	Wrong number of arguments.

Any condition values returned by LIB$SCOPY_DXDX.

The Return Character at Cursor routine returns the character at the current physical cursor position.

Format

SMG$GET_CHAR_AT_PHYSICAL_CURSOR pasteboard-id ,character-code [,rendition] [,user-rendition]

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 from which to retrieve the character. 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.

character-code

OpenVMS usage:	byte_unsigned
type:	byte (unsigned)
access:	write only
mechanism:	by reference

Returned character code. The character-code argument is the address of an unsigned byte into which is written the character's ASCII code.

rendition

OpenVMS usage:	byte_unsigned
type:	byte (unsigned)
access:	write only
mechanism:	by reference

Receives the rendition code associated with the character code returned by the character-code argument. The rendition argument is the address of an unsigned byte into which is written the rendition code.

user-rendition

OpenVMS usage:	byte_unsigned
type:	byte (unsigned)
access:	write only
mechanism:	by reference

Receives the user rendition code associated with the character code returned by the character-code argument. The user-rendition argument is the address of an unsigned byte into which is written the user rendition code.

Description

SMG$GET_CHAR_AT_PHYSICAL_CURSOR returns the character that occupies the screen position corresponding to the current physical cursor position.

Note If the Screen Management Facility has not written to the screen location occupied by the physical cursor, then the contents of that position are unknown.

If the returned character has an ASCII value less than 32 (decimal), it is not a printable character. Rather, it is an internal terminal-independent code denoting what should be displayed at that position (for example, an element of the line-drawing character set). Do not attempt to use this code for subsequent output operations.

SMG$GET_CHAR_AT_PHYSICAL_CURSOR may not return valid data if display batching or pasteboard batching is on. This can occur because the cursor position does not reflect any calls to SMG$SET_PHYSICAL_CURSOR or the SMG$SET_CURSOR_xxxx routines until batching ends.

Condition Values Returned

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

The Get Display Attributes routine receives the attributes associated with a virtual display.

Format

SMG$GET_DISPLAY_ATTR display-id [,height] [,width] [,display-attributes] [,video-attributes] [,character-set] [,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 for which information is requested. 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.

height

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

Receives the number of rows in the display. The optional height argument is the address of a signed longword into which the height is written.

width

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

Receives the number of columns in the display. The optional width argument is the address of a signed longword into which is written the number of columns in the display.

display-attributes

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

Receives the current default display attributes. The optional display-attributes argument is the address of an unsigned longword into which the current display attributes are written.

Valid values for display-attributes are as follows:

SMG$M_BORDER	Specifies a bordered display. If omitted, the display is not bordered.
SMG$M_BLOCK_BORDER	Specifies a block bordered display. If omitted, the display is not bordered.
SMG$M_DISPLAY_CONTROLS	Specifies that control characters such as carriage return and line feed are displayed as graphic characters, if your terminal supports them.
SMG$M_TRUNC_ICON	Specifies that an icon (generally a diamond shape) is displayed where truncation of a line exceeding the width of the virtual display has occurred.

video-attributes

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

Receives the current default video attributes. The optional video-attributes argument is the address of an unsigned longword into which the current video attributes are written.

Valid video attributes are as follows:

SMG$M_BLINK	Displays blinking characters.
SMG$M_BOLD	Displays characters in higher-than-normal intensity.
SMG$M_REVERSE	Displays characters in reverse video; that is, using the opposite of the default rendition of the virtual display.
SMG$M_UNDERLINE	Displays underlined characters.
SMG$M_INVISIBLE	Specifies invisible characters; that is, the characters exist in the virtual display but do not appear on the pasteboard.
SMG$M_USER1 through SMG$M_USER8	Displays user-defined attributes.

character-set

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

Receives the default character set for all text in this virtual display. The optional character-set argument is the address of an unsigned longword that specifies the character set. Valid values are SMG$C_ASCII (the default) and SMG$C_SPEC_GRAPHICS.

flags

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

Optional bit mask specifying attributes of the specified display. The flags argument is the address of an unsigned longword containing the flag. Valid values for flags are as follows:

SMG$M_SUBPROCESS	Display has a subprocess attached to it.
SMG$M_MENU	Display contains a menu.
SMG$M_VIEWPORT	Display contains a viewport.

Description

SMG$GET_DISPLAY_ATTR receives the attributes of a virtual display.

Condition Values Returned

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

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

5935PRO_019.HTML