![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
|
Updated:
11 December 1998
|
OpenVMS RTL Screen Management (SMG$) Manual
SMG$PUT_LINE_WIDE
The Write Double-Width Line routine writes a line of double-width text
to a virtual display.
Format
SMG$PUT_LINE_WIDE display-id ,text [,line-advance] [,rendition-set]
[,rendition-complement] [,flags] [,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.
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 integer that contains the number of lines to advance.
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 take 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.
Description
SMG$PUT_LINE_WIDE writes lines of double-width text to the virtual
display. SMG$PUT_LINE_WIDE 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 filled with blanks.
If the flags argument specifies wrapping, lines are
scrolled line-advance times to make room for the
overflow characters in the "next" line. If
flags does not specify wrapping, excess characters are
discarded.
Following a call to SMG$PUT_LINE_WIDE, the virtual cursor position is
set to column 1 of the next line where output should occur. The next
line where output should occur is determined by the
line-advance argument; line-advance
defaults to 1 so that subsequent calls to SMG$PUT_LINE_WIDE will not
cause overprinting.
Other routines that you can use to write text to a virtual display are
SMG$PUT_LINE and SMG$PUT_LINE_HIGHWIDE.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVDIS_ID
|
Invalid
display-id.
|
|
SMG$_WILUSERMS
|
Pasteboard is not a video terminal.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
|
LIB$_INVSTRDES
|
Invalid string descriptor.
|
Example
|
C+
C This Fortran example program demonstrates the use of
C SMG$PUT_LINE_WIDE.
C
C Include the SMG definitions. In particular, we want SMG$M_BORDER and
C SMG$M_UNDERLINE.
C-
INCLUDE '($SMGDEF)'
INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, SMG$PUT_LINE_WIDE
INTEGER DISPLAY1, PASTE1, ROWS, COLUMNS, STATUS
CHARACTER*34 TEXT(3)
C+
C Create a virtual display with a border by calling
C SMG$CREATE_VIRTUAL_DISPLAY.
C-
ROWS = 7
COLUMNS = 70
STATUS = SMG$CREATE_VIRTUAL_DISPLAY
1 (ROWS, COLUMNS, DISPLAY1, SMG$M_BORDER)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Call SMG$CREATE_PASTEBOARD to create the pasteboard.
C-
STATUS = SMG$CREATE_PASTEBOARD (PASTE1)
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Use SMG$PUT_LINE to put data in the virtual display.
C-
TEXT(1) = 'This virtual display has 7'
TEXT(2) = 'rows and 70 columns.'
TEXT(3) = 'Text entered by SMG$PUT_LINE_WIDE.'
C+
C After the first line of text is printed, advance two lines.
C-
STATUS = SMG$PUT_LINE_WIDE ( DISPLAY1, TEXT(1), 2 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Underline the next line of text. Notice that 34 characters are being
C underlined. Advance one line of text after displaying the line.
C-
STATUS = SMG$PUT_LINE_WIDE ( DISPLAY1, TEXT(2), 1,
1 SMG$M_UNDERLINE )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Display the third line of text.
C-
STATUS = SMG$PUT_LINE_WIDE ( DISPLAY1, TEXT(3) )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
C+
C Paste the virtual display using SMG$PASTE_VIRTUAL_DISPLAY.
C-
STATUS = SMG$PASTE_VIRTUAL_DISPLAY ( DISPLAY1, PASTE1, 4, 5 )
IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS))
END
|
The output generated by this Fortran program is shown in Figure SMG-35.
Figure SMG-35 Output Generated by Fortran Program Calling
SMG$PUT_LINE_WIDE
SMG$PUT_PASTEBOARD
The Output Pasteboard Using Routine routine accesses the contents of a
pasteboard.
Format
SMG$PUT_PASTEBOARD pasteboard-id ,action-routine [,user-argument]
[,flags]
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 |
Pasteboard identifier. The pasteboard-id argument is
the address of an unsigned longword containing the pasteboard
identifier.
action-routine
| OpenVMS usage: |
procedure |
| type: |
procedure value |
| access: |
read only |
| mechanism: |
by value |
Pasteboard routine to be called. The action-routine
argument is the address of the routine's procedure value. Because SMG$
cannot determine the resulting type of device, device-independent
characters (plus sign [+], minus sign [-], vertical bar [|]) are used
to draw lines. SMG$PUT_PASTEBOARD passes the following data structure
to action-routine.
user-argument
| OpenVMS usage: |
user_arg |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by value |
The argument you supply to the action-routine. The
user-argument argument is an unsigned longword that
contains the value to be passed to the action routine. If
user-argument is omitted, a 0 will be passed as the
user argument.
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Optional bit mask that specifies whether a form feed is passed to the
action routine. The flags argument is the address of
an unsigned longword that contains the flag. Valid values for
flags are as follows:
|
0
|
No form-feed line is sent.
|
|
SMG$M_FORM_FEED
|
The first line passed to the action routine is a form feed.
|
Description
The SMG$PUT_PASTEBOARD routine accesses the contents of a pasteboard.
The caller specifies an action routine that will be called once for
each line in the pasteboard. The action routine will be passed a
descriptor for that line followed by a user-specified argument.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
Other
|
Any error returned by the action routine.
|
SMG$PUT_STATUS_LINE
The Output Line of Text to Hardware Status Line routine outputs a line
of text to the hardware status line.
Format
SMG$PUT_STATUS_LINE pasteboard-id ,text
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 containing the hardware status line. The
pasteboard-id argument is the address of an unsigned
longword that contains the pasteboard identifier.
text
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
The characters to be written to the hardware status line. The
text argument is the address of a descriptor pointing
to the text.
Description
The SMG$PUT_STATUS_LINE routine outputs a line of text to the
terminal's hardware status line. Some terminals have a hardware status
line at the bottom (25th line) of the screen. If this status line has
been set as "host writable," you can use this routine to
output a line of text to the status line. (If the hardware status line
is not available, the error SMG$_OPNOTSUP is returned.) The text is
output in reverse video.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SMG$_INVPAS_ID
|
Invalid
pasteboard-id.
|
|
SMG$_OPNOTSUP
|
No hardware status line available.
|
|
SMG$_WRONUMARG
|
Wrong number of arguments.
|
|
LIB$_INVARG
|
Invalid argument.
|
SMG$READ_COMPOSED_LINE
The Read Composed Line routine reads a line of input composed of normal
keystrokes and equivalence strings.
Format
SMG$READ_COMPOSED_LINE keyboard-id [,key-table-id]
,resultant-string [,prompt-string] [,resultant-length] [,display-id]
[,flags] [,initial-string] [,timeout] [,rendition-set]
[,rendition-complement] [,word-terminator-code]
RETURNS
| OpenVMS usage: |
cond_value |
| type: |
longword (unsigned) |
| access: |
write only |
| mechanism: |
by value |
Arguments
keyboard-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the virtual keyboard from which input is to be read. 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.
key-table-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Specifies the key definition table to be used for translating
keystrokes. The key-table-id argument is the address
of an unsigned longword that contains the key definition table
identifier.
The key definition table identifier is returned by SMG$CREATE_KEY_TABLE.
resultant-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
write only |
| mechanism: |
by descriptor |
String into which SMG$READ_COMPOSED_LINE writes the complete composed
line. The resultant-string argument is the address of
a descriptor pointing to the string in which the composed line is
written.
prompt-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
String used to prompt for the read operation. The
prompt-string argument is the address of a descriptor
pointing to the prompt string.
resultant-length
| OpenVMS usage: |
word_unsigned |
| type: |
word (unsigned) |
| access: |
write only |
| mechanism: |
by reference |
Receives the number of characters read or the maximum length of
resultant-string, whichever is less. The
resultant-length argument is the address of an
unsigned longword into which SMG$READ_COMPOSED_LINE writes the number
of characters read.
display-id
| OpenVMS usage: |
identifier |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Display identifier. The display-id argument is the
address of an unsigned longword that contains the display identifier.
This argument is optional only if you are not using the Screen
Management Facility's output routines.
If you are using the Screen Management Facility input and output
routines, this argument specifies the virtual display in which the
input is to occur. The virtual display specified must be pasted to the
same pasteboard as specified by keyboard-id and must
not be occluded. You cannot accept input from an occluded area of the
virtual display.
In the case of multiple virtual displays, each virtual display has an
associated virtual cursor position. At the same time, there is a single
physical cursor position corresponding to the current location of the
physical cursor. If the display-id argument is
specified, the read begins at the current virtual cursor position in
the specified virtual display. If the display identifier is omitted,
the read begins in the current physical cursor position. The length of
the prompt-string plus the key entered is limited to
the number of visible columns in the display.
Note
This virtual display must be pasted in column 1 and may not have any
other virtual displays to its right. This restriction is necessary
because otherwise any occurrence of Ctrl/R or Ctrl/U would blank out
the entire line, including any output pasted to the right. To
circumvent this restriction, you can use SMG$REPAINT_LINE whenever a
Ctrl/R or Ctrl/U is encountered.
|
flags
| OpenVMS usage: |
mask_longword |
| type: |
longword (unsigned) |
| access: |
read only |
| mechanism: |
by reference |
Optional bit mask that specifies enabled keys. The
flags argument is the address of an unsigned longword
that contains the flag. Valid values for flags are as
follows:
|
0
|
Line editing is enabled and function keys (F6 to F14) cannot be used.
|
|
SMG$M_FUNC_KEYS
|
Function keys (F6 to F14) may be used and line editing is disabled.
|
|
SMG$M_NOKEEP
|
Lines entered in the recall buffer are not saved.
|
|
SMG$M_NORECALL
|
Line recall is disabled for this I/O only.
|
Because the OpenVMS terminal driver uses the function keys (F6 to F14)
for line editing on some terminals, you cannot have function keys and
line editing enabled at the same time.
initial-string
| OpenVMS usage: |
char_string |
| type: |
character string |
| access: |
read only |
| mechanism: |
by descriptor |
Optional string that contains the initial characters of the field. The
initial-string argument is the address of a descriptor
pointing to the string. The string is written to the display in the
input area, as if it had been entered from the keyboard. It may be
edited in the usual way (provided that the SMG$M_FUNC_KEYS flag is not
set).
timeout
| OpenVMS usage: |
longword_signed |
| type: |
longword (signed) |
| access: |
read only |
| mechanism: |
by reference |
Optional timeout count. The timeout argument is the
address of a signed longword containing the timeout count. If the
timeout argument is specified, all characters entered
before the timeout are returned in the buffer. If the
timeout argument is omitted, characters are returned
in the buffer until a terminator is encountered.
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.
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif)