Document revision date: 30 March 2001

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

| privacy and legal statement |
5935PRO_009.HTML