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$PUT_CHARS_WIDE

The Write Double-Width Characters routine writes double-width characters to a virtual display.

Format

SMG$PUT_CHARS_WIDE display-id ,text [,start-row] [,start-column] [,rendition-set] [,rendition-complement] [,character-set]


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 affected. 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.

text


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

Characters to be written to the virtual display. The text argument is the address of a descriptor pointing to the text.

start-row


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

Specifies the line at which output begins. The start-row argument is the address of a signed longword that contains the line number. If start-row is omitted, output begins on the current line.

start-column


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

Specifies the column at which output begins. If start-column is omitted, output begins on the current column. The start-column argument is the address of a signed longword that contains the column number.

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

character-set


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

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

Description

SMG$PUT_CHARS_WIDE writes double-width text to the specified virtual display, possibly overwriting any existing text. The line cannot contain a mixture of single- and double-width characters; if the line previously contained any single-width characters, those characters are replaced with blanks. The virtual cursor is left at the first character position following the text written.

If the display has the SMG$M_TRUNC_ICON attribute, SMG$PUT_CHARS_WIDE outputs the truncation icon when the line overflows the display.


Condition Values Returned

SS$_NORMAL Normal successful completion.
SMG$_INVCOL Invalid column.
SMG$_INVDIS_ID Invalid display-id.
SMG$_INVROW Invalid row.
SMG$_WILUSERMS Pasteboard is not a video terminal.
SMG$_WRONUMARG Wrong number of arguments.
LIB$_INVSTRDES Invalid string descriptor.

SMG$PUT_HELP_TEXT

The Output Help Text to the Display routine retrieves and outputs the help text for the specified topic in the virtual display provided.

Format

SMG$PUT_HELP_TEXT display-id [,keyboard-id] [,help-topic] [,help-library] [,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

Display identifier of the virtual display to which the help text is written. The display-id argument is the address of an unsigned longword that contains this virtual display identifier. Note that this display must be pasted and cannot be occluded or batched.

keyboard-id


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

Optional keyboard identifier of the virtual keyboard used for input. The keyboard-id argument is the address of an unsigned longword that contains this virtual keyboard identifier. If the keyboard-id parameter is not specified, prompting is disabled.

help-topic


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

Optional help topic. The help-topic argument is the address of a descriptor pointing to the help topic string.

help-library


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

Optional help library name. The help-library argument is the address of a descriptor pointing to the help library name. The default is SYS$HELP:HELPLIB.HLB.

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

SMG$PUT_HELP_TEXT lets you retrieve and output help text for a specified topic in the virtual display specified. The text is output to the virtual display's scrolling region. If you specify the keyboard-id argument, you are prompted for input when the last line of the virtual scrolling region is reached. In response to this prompt you can either press the Return key to continue the display, or enter a new topic to receive help on. Note that the virtual display specified by display-id cannot be batched or contain a viewport. If the keyboard-id argument is specified, the virtual display cannot be occluded and must contain at least three rows.

Condition Values Returned

SS$_NORMAL Normal successful completion.
SMG$_ILLBATFNC The virtual display or pasteboard was batched.
SMG$_INVDIS_ID The display-id is illegal, has an associated viewport, or is occluded.
SMG$_NOTPASTED The virtual display specified by display-id is not pasted.
SMG$_ xxxx Any condition value returned by SMG$SET_CURSOR_ABS or SMG$CHECK_FOR_OCCLUSION.
LIB$_ xxxx Any condition value returned by LIB$FIND_IMAGE_SYMBOL.
LBR$_ xxxx Any condition value returned by LBR$OUTPUT_HELP.

SMG$PUT_LINE

The Write Line to Virtual Display routine writes a line of text to a virtual display, beginning at the current virtual cursor position.

Format

SMG$PUT_LINE display-id ,text [,line-advance] [,rendition-set] [,rendition-complement] [,flags] [,character-set] [,direction]


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 affected. 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.

text


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

The characters to be written to the virtual display. The text argument is the address of a descriptor pointing to the text.

line-advance


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

Specifies the number of lines to advance after output. The line-advance argument is the address of a signed longword that contains the number of lines to advance. The default is 1. If you specify 0 for line-advance, SMG$PUT_LINE overwrites any existing text.

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

flags


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

Optional bit mask that specifies the action to be taken if the text does not fit on the line. The flags argument is the address of an unsigned longword that contains the flag. The flags argument accepts the following values:
0 Does not wrap (default).
SMG$M_WRAP_CHAR Wraps at the last character on the line.
SMG$M_WRAP_WORD Wraps at the last space on the line.

character-set


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

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

direction


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

Specifies the direction to scroll, if scrolling is necessary. The direction argument is the address of a longword bit mask that contains the direction code. Valid values are SMG$M_UP (default) and SMG$M_DOWN.

Description

SMG$PUT_LINE writes lines of text to the virtual display, beginning at the current line. Once text reaches the bottom or top line (depending on the scrolling direction), subsequent calls to this routine cause the display to scroll. SMG$PUT_LINE writes out the entire line, starting at the current virtual cursor position. If the caller's text does not span the entire line, the line is padded with blanks.

If flags specifies wrapping, lines are scrolled line-advance times to make room for the overflow characters in the "next" line. The "next" line is determined by the scrolling direction. If flags does not specify wrapping, excess characters are discarded.


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_027.HTML