Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS RTL Screen Management (SMG$) Manual


Previous Contents Index


SMG$BEGIN_DISPLAY_UPDATE

The Begin Batching of Display Updates routine saves, or batches, all output to a virtual display until a matching call to SMG$END_DISPLAY_UPDATE is encountered.

Format

SMG$BEGIN_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 for which output is to be batched. 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.


Description

SMG$BEGIN_DISPLAY_UPDATE lets you make more than one change to a display and have the changes appear only after all changes are complete. Thus, the user sees the display change from its initial state to its final state, without seeing any of the intermediate states.

Batching terminates when SMG$END_DISPLAY_UPDATE has been called the same number of times for a given display as has SMG$BEGIN_DISPLAY_UPDATE. The Screen Management Facility keeps track of batching for a given display; thus, the calls to the SMG$BEGIN_DISPLAY_UPDATE and SMG$END_DISPLAY_UPDATE need not occur in the same module.


Condition Values Returned

SS$_NORMAL Normal successful completion.
SMG$_BATWAS_ON Successful completion; batching has already been initiated.
SMG$_INVDIS_ID Invalid display-id.
SMG$_WRONUMARG Wrong number of arguments.

SMG$BEGIN_PASTEBOARD_UPDATE

The Begin Batching of Pasteboard Updates routine saves, or batches, all output to a pasteboard until a matching call to SMG$END_PASTEBOARD_UPDATE is encountered.

Format

SMG$BEGIN_PASTEBOARD_UPDATE 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 for which output is to be batched. 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$BEGIN_PASTEBOARD_UPDATE lets you make more than one change to a pasteboard and have the changes appear only after all changes are complete. Thus, the user sees the pasteboard change from its initial state to its final state, without seeing any of the intermediate states.

Batching terminates when SMG$END_PASTEBOARD_UPDATE has been called the same number of times for a given pasteboard as has SMG$BEGIN_PASTEBOARD_UPDATE. The Screen Management Facility keeps track of batching for a given pasteboard; thus, the calls to the SMG$BEGIN_PASTEBOARD_UPDATE and SMG$END_PASTEBOARD_UPDATE need not occur in the same module.


Condition Values Returned

SS$_NORMAL Normal successful completion.
SMG$_BATWAS_ON Successful completion; batching has already been initiated.
SMG$_INVPAS_ID Invalid pasteboard-id.
SMG$_WRONUMARG Wrong number of arguments.

SMG$CANCEL_INPUT

The Cancel Input Request routine immediately cancels any read-in-progress that was issued by SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, or SMG$READ_VERIFY.

Format

SMG$CANCEL_INPUT keyboard-id


RETURNS


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


Argument

keyboard-id


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

Specifies the virtual keyboard for which the input is to be canceled. The keyboard-id argument is the address of an unsigned longword that contains the keyboard identifier.

The keyboard identifier is returned by SMG$CREATE_VIRTUAL_KEYBOARD.


Description

SMG$CANCEL_INPUT causes immediate termination of an SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, or SMG$READ_VERIFY input operation from a terminal. The condition code SS$_CANCEL or SS$_ABORT is returned to those routines when you use SMG$CANCEL_INPUT. Note that if the specified virtual keyboard is associated with an OpenVMS RMS file, this procedure has no effect because it is not possible to cancel an outstanding RMS input operation.

Condition Values Returned

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

SMG$CHANGE_PBD_CHARACTERISTICS

The Change Pasteboard Characteristics routine lets you change the characteristics associated with a pasteboard.

Format

SMG$CHANGE_PBD_CHARACTERISTICS pasteboard-id [,desired-width] [,width] [,desired-height] [,height] [,desired-background-color] [,background-color]


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 whose characteristics are to be changed. 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.

desired-width


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

New width for the pasteboard. The desired-width argument is the address of a signed longword that contains the desired width. If omitted, the width does not change.

width


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

Receives the physical width of the pasteboard. The width argument is the address of a signed longword into which is written the actual width of the pasteboard.

If the terminal cannot be set exactly to desired-width, width may be larger than desired-width. If the physical width of the terminal is smaller than desired-width, width may be smaller than desired-width.

desired-height


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

New height for the pasteboard. The desired-height argument is the address of a signed longword that contains the desired height of the pasteboard. If desired-height is omitted, the height does not change.

height


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

Receives the physical height of the pasteboard. The height argument is the address of a signed longword into which is written the actual height of the pasteboard.

If the terminal cannot be set exactly to desired-height, height may be larger than desired-height. If the physical height of the terminal is smaller than desired-height, height may be smaller than desired-height.

desired-background-color


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

Symbolic name for the desired background color. The desired-background-color argument is the address of an unsigned longword that contains the desired color.

The symbols listed below are defined in $SMGDEF. Valid values for desired-background-color are as follows:
SMG$C_COLOR_WHITE Light background
SMG$C_COLOR_BLACK Dark background
SMG$C_COLOR_BLUE Blue background
SMG$C_COLOR_CYAN Cyan (green-blue) background
SMG$C_COLOR_GREEN Green background
SMG$C_COLOR_MAGENTA Magenta background
SMG$C_COLOR_RED Red background
SMG$C_COLOR_YELLOW Yellow background
SMG$C_COLOR_LIGHT White background
SMG$C_COLOR_DARK Black background
SMG$C_COLOR_USER1 User-defined background 1
SMG$C_COLOR_USER2 User-defined background 2
SMG$C_COLOR_USER3 User-defined background 3
SMG$C_COLOR_USER4 User-defined background 4
SMG$C_COLOR_USER5 User-defined background 5
SMG$C_COLOR_USER6 User-defined background 6
SMG$C_COLOR_USER7 User-defined background 7
SMG$C_COLOR_USER8 User-defined background 8

If you omit desired-background-color, or if the terminal hardware does not support the background color specified, the background color is not changed.

background-color


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

Receives the background color chosen. The background-color argument is the address of an unsigned longword into which is written the background color.

This routine may return any of the values listed in the desired-background-color argument description or SMG$C_COLOR_UNKNOWN. If the desired-background-color argument is omitted, the value of background-color does not change.


Description

SMG$CHANGE_PBD_CHARACTERISTICS lets you change the width, height, and background color associated with a pasteboard.

If necessary, this routine will notify the OpenVMS operating system of the change in pasteboard characteristics by updating the terminal characteristics displayed when you enter the DCL command SHOW TERMINAL.

Do not use SMG$CHANGE_PBD_CHARACTERISTICS on a batched pasteboard.


Condition Values Returned

SS$_NORMAL Normal successful completion.
SMG$_INVCOLARG Unknown background color specified.
SMG$_INVPAGARG Invalid height of 0 desired.
SMG$_INVWIDARG Invalid width of 0 desired.
SMG$_PBDIN_USE Cannot change characteristics while batching is on.
SMG$_WRONUMARG Wrong number of arguments.
SS$_xxx Any error from $QIOW.

SMG$CHANGE_RENDITION

The Change Default Rendition routine changes the video attributes for all or part of a virtual display.

Format

SMG$CHANGE_RENDITION display-id ,start-row ,start-column ,number-of-rows ,number-of-columns [,rendition-set] [,rendition-complement]


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 whose default rendition is to be changed. 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

Starting row position to receive the new rendition. The start-row argument is the address of a signed longword that contains the starting row number.

start-column


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

Starting column position to receive the new rendition. The start-column argument is the address of a signed longword that contains the starting column number.

number-of-rows


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

Number of rows to receive the new rendition. The number-of-rows argument is the address of a signed longword that contains the number of rows to be affected.

number-of-columns


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

Number of columns to receive the new rendition. The number-of-columns argument is the address of a signed longword that contains the number of columns to be affected.

rendition-set


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

Attribute specifier. The optional rendition-set argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be set in the display. The following attributes can be specified using the rendition-set argument:
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.

The display-id argument must be specified when you use the rendition-set argument.

rendition-complement


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

Attribute complement specifier. The optional rendition-complement argument is the address of a longword bit mask in which each attribute set causes the corresponding attribute to be complemented in the display. All of the attributes that can be specified with the rendition-set argument can be complemented with the rendition-complement argument. The display-id argument must be specified when you use the rendition-complement argument.

The optional arguments rendition-set and rendition-complement let the user control the attributes of the virtual display. The rendition-set argument sets certain virtual display attributes, while rendition-complement complements these attributes. If the same bit is specified in both the rendition-set and rendition-complement parameters, rendition-set is evaluated first, followed by rendition-complement. By using these two parameters together, the user can control each virtual display attribute in a single procedure call. On a single-attribute basis, the user can cause the following transformations:
Set Complement Action
0 0 Attribute set to default
1 0 Attribute on
0 1 Attribute set to complement of default setting
1 1 Attribute off


Description

This procedure changes the default video rendition of a rectangular block of text already in the specified virtual display. For example, you might use this procedure to redisplay a particular row in reverse video.

Condition Values Returned

SS$_NORMAL Normal successful completion.
SMG$_INVARG Invalid number of rows, invalid number of columns, unrecognized rendition-set code, or unrecognized rendition-complement code.
SMG$_INVCOL Invalid start-column. The specified column is outside the virtual display.
SMG$_INVDIS_ID Invalid display-id.
SMG$_INVROW Invalid start-row. The specified row is outside the virtual display.
SMG$_NO_CHADIS No change in virtual display.
SMG$_WRONUMARG Wrong number of arguments.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
5935PRO_009.HTML