VMS Help  —  RTL Routines, SMG$  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]

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.
Close Help