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]
1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
2 – 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_ Displays underlined characters.
UNDERLINE
SMG$M_ Specifies invisible characters; that is, the
INVISIBLE characters exist in the virtual display but do
not appear on the pasteboard.
SMG$M_USER1 Displays user-defined attributes.
through
SMG$M_USER8
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
word-terminator-code
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Key terminator code. The word-terminator-code argument is an
unsigned word into which is written a code indicating what
character or key terminated the read. Key terminator codes are
of the form SMG$K_TRM_keyname.