The Read and Verify a String routine reads a sequence of
characters and verifies the sequence.
Format
SMG$READ_VERIFY keyboard-id ,resultant-string ,initial-string
,picture-string ,fill-character
,clear-character [,prompt-string]
[,modifiers] [,timeout] [,placeholder-arg]
[,initial-offset] [,word-terminator-code]
[,display-id] [,alternate-echo-string]
[,alternate-display-id] [,rendition-set]
[,rendition-complement] [,input-length]
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
Keyboard identifier. The keyboard-id argument is the address of
an unsigned longword containing the identifier of the virtual
keyboard from which to read.
The virtual keyboard is created by calling the SMG$CREATE_
VIRTUAL_KEYBOARD routine.
resultant-string
OpenVMS usage:char_string
type: character string
access: write only
mechanism: by descriptor
Output string into which SMG$READ_VERIFY writes the characters
that are read. The resultant-string argument is the address of a
descriptor pointing to this output string.
initial-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Input string that contains the initial characters of the field.
The initial-string argument is the address of a descriptor
pointing to the input string.
picture-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
String that contains a picture of what the field is to look
like. The picture-string argument is the address of a descriptor
pointing to the picture string.
For more information on the legal values for the picture string,
see the terminal driver section of the OpenVMS I/O User's
Reference Manual.
fill-character
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Fill character. The fill-character argument is the address of a
descriptor pointing to the string that contains the character to
be used as a fill character in the initial-string argument.
clear-character
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Clear character. The clear-character argument is the address of
a descriptor pointing to the string that contains the character
to be displayed for each occurrence of fill-character in initial-
string.
prompt-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Prompt string. The prompt-string argument is the address of a
descriptor pointing to the string that SMG$READ_VERIFY uses as
the prompt for the read operation. This is an optional argument.
modifiers
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Modifiers. The modifiers argument is a longword bit mask that
specifies optional behavior. The bits defined are the same as
for the $QIO item-list entry TRM$_MODIFIERS. This is an optional
argument.
Valid values for modifiers are as follows:
TRM$M_TM_AUTO_TAB Field is full when last character is entered.
TRM$M_TM_CVTLOW Converts lowercase characters to uppercase
characters.
TRM$M_TM_NOECHO Characters entered are not echoed on the
screen.
TRM$M_TM_NOEDIT Advanced editing is disabled for this read
operation.
TRM$M_TM_NORECALL Line recall is disabled.
TRM$M_TM_PURGE Type-ahead buffer is purged before read is
begun.
TRM$M_TM_R_JUST Input is right justified.
TRM$M_TM_ Termination character, if any, is not
TRMNOECHO displayed.
The TRM$ symbols are defined by the $TRMDEF macro/module in
system symbol libraries supplied by OpenVMS. See the terminal
driver section of the OpenVMS I/O User's Reference Manual for
more information on modifiers for read operations.
timeout
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Timeout count. The timeout argument is the address of a signed
longword that contains the timeout value. The timeout argument is
optional. If timeout is specified, all characters typed in before
the timeout or before a terminator is entered are returned in
the buffer. If timeout is omitted, characters are returned in the
buffer until a terminator is seen.
placeholder-arg
OpenVMS usage:unspecified
type: unspecified
access: read only
mechanism: unspecified
Placeholder argument. The OpenVMS terminal driver ignores this
argument when performing a read-verify.
initial-offset
OpenVMS usage:longword_signed
type: longword (signed)
access: read only
mechanism: by reference
Input string offset. The initial-offset argument is the address
of a signed longword that contains the number of characters (from
the initial-string argument) to output after the prompt before
waiting for input.
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 SMG$READ_VERIFY writes a code indicating
what character or key terminated the read. Key terminator codes
are of the form SMG$K_TRM_keyname.
display-id
OpenVMS usage:identifier
type: longword (unsigned)
access: read only
mechanism: by reference
Display identifier. The optional display-id argument is the
address of an unsigned longword that contains the identifier
of the virtual display in which the read is to be performed.
If display-id is specified, SMG$READ_VERIFY begins the read at
the current virtual cursor position in that virtual display. If
omitted, the read begins in the current physical cursor position.
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 omitted,
the read begins in the current physical cursor position. Note
that the length of the prompt-string, the initial-offset, and the
string entered is limited to the number of visible columns in the
display.
alternate-echo-string
OpenVMS usage:char_string
type: character string
access: read only
mechanism: by descriptor
Alternate echo string. The alternate-echo-string argument is a
string that is printed after the first character is typed during
the read operation. This is an optional argument.
alternate-display-id
OpenVMS usage:identifier
type: longword (signed)
access: read only
mechanism: by reference
Alternate display identifier. The alternate-display-id is a
signed longword containing the identifier of the virtual display
in which the alternate-echo-string argument is to be printed.
This is an optional argument. If specified, the output begins
at the current virtual cursor position in that virtual display.
If omitted, the value of the display-id argument is used as the
default. If display-id is not specified, the output begins in the
current physical cursor position.
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 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 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 in which
the read is done. 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 transformations
shown in the following table.
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
input-length
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Number of characters entered by the user. The input-length
argument is the address of an unsigned word containing this
number.