1 _INQUIRE
 Requests  assignment  of  a given local or global DCL symbol to the
 string entered in response to a  specified  prompt.   The  _INQUIRE
 command  is  a  functionally enhanced, upward-compatible version of
 the standard VMS INQUIRE  command.   Note  the  underscore  as  the
 first  character  of  the  command.  This is to distinguish it from
 the DCL INQUIRE command.

    Format:

       _INQUIRE symbol-name [prompt-string]

 The _INQUIRE command is intended primarily for use  in  interactive
 command  procedures  run  from  terminals.   In this case, _INQUIRE
 prompts/responses are to/from  SYS$COMMAND.   When  SYS$COMMAND  is
 not  a  terminal (e.g. batch mode),  prompting is to SYS$OUTPUT and
 responses are read  from  SYS$COMMAND.  When  used  in  this  mode,
 qualifiers  noted  as  being  specific to terminal function have no
 effect.
2 Parameters
 prompt-string

 Specifies the prompt to be  displayed  at  the  terminal  when  the
 INQUIRE  command  is  executed.   If the prompt string contains any
 lowercase characters, blanks or tabs, or an at sign character  (@),
 enclose it in quotation marks (").

 When  the  system  displays  the  prompt string at the terminal, it
 generally places a colon (:) and a space at the end of the  string.
 (See the /PUNCTUATION qualifier.)

 If  you  do not specify a prompt string, the symbol name is used as
 the prompt.

 symbol-name

 Specifies a 1- through 255-alphanumeric character  symbol   to   be
 given a value.  This parameter is required.
2 Qualifiers
!
/BUFLEN=n_(n=255_(D))
 /BUFLEN is used to set the maximum response length to "n" characters.
 The  inquiry  (read)  operation  will  always be terminated after "n"
 characters have been typed.

 Legal values for "n" range from 0 through 255.
/DEVICE=name
 Specifies a default device to override the default of SYS$COMMAND:.
/ECHO_(D)
/NOECHO
 /NOECHO  causes  response  characters  not  to  be  echoed  at  the
 terminal.

 /ECHO is the default.
/EOF=label
 Specifies a DCL label that is the  target  of  the  next  statement
 executed  if  the  response  terminates with an end-of-file status.
 This qualifier can be used in both batch and terminal modes.   (For
 terminals,   control-Z   (end-of-file)  is  treated  as  any  other
 terminator would be, but is also used to signal the end-of-file.)
/ERASE=erase-item
 Causes an erase operation on an ANSI-compatible CRT terminal  as  a
 part  of  the  prompting.   There  are  four  possible  values  for
 erase-item.

 EOL     The prompt  is  written  and  the  remainder  of  the  line
         containing the cursor is cleared.
 EOS     The  prompt  is  written  and  the  remainder of the screen
         following the cursor is cleared.
 LINE    The line  containing  the  cursor  is  cleared  before  the
         prompt   is   written,   but  after  any  specified  cursor
         positioning is performed.
 SCREEN  The entire screen is erased before the prompt is written.

/ESCAPE
/NOESCAPE_(D)
 /ESCAPE causes escape sequences to be recognized as  terminating  a
 response.   (This is independent of whether the terminal is set for
 /ESCAPE  or  not.)   Explicit  specification  of  /ESCAPE   implies
 /TERMINATOR,  which means that the escape sequence will be included
 in the returned string.   Note  that  escape  sequences  are  never
 echoed regardless of the state of the ECHO qualifier.

 If  the  terminating  escape  sequence is an invalid one, the FATAL
 status (SS$_BADESCAPE)  is  converted  to  INFORMATIONAL,  and  the
 terminator  string returned includes all characters through the one
 causing the escape sequence to be invalid.

 /NOESCAPE is the default.
/ET_(D)
/NOET
 /NOET prevents the response terminator from being echoed.  It  does
 not, alas, rid the universe of excessively cute alien cash cows.

 Note  that  the  terminator  is not echoed if /NOECHO is specified,
 regardless of  this  qualifer's  setting.   Also,  escape  sequence
 terminators (see /ESCAPE) are never echoed.

 Note  that  with  the  combination  of  /NOET,  /NOPUNCTUATION  and
 /NOECHO, the terminal display should be unaffected  by  the  action
 of the command.

 /ET is the default.
/FILTER_(D)
/NOFILTER
 /NOFILTER causes DEL, Ctrl-U  and Ctrl-R  not  to be interpreted by
 the terminal driver.  All line editing is disabled.
/GLOBAL
 Causes  all  symbol  definitions made by the _INQUIRE command to be
 in the global DCL symbol table.  The complement is /LOCAL.

 /LOCAL is the default.
/HLPLIB=file
 Causes the indicated file to be accessed  as  an  interactive  help
 library  if  the  PF2  key  (<ESC>-O-Q sequence) is depressed on an
 ANSI-compatible terminal.  The actual help text  presented  to  the
 help  library  system  will  be  the  string  formed by joining (in
 order): the value of /HLPPFX, the user's text prior to  the  <PF2>,
 followed  by  the  value  of  /HLPSFX.   If  any  of  these are not
 specified, they are taken to be null.

 For example, the qualifiers /HLPLIB=HELPLIB/HLPPFX=AIRCRAFT with  a
 response  of  "orville<PF2>"  would  cause  "AIRCRAFTorville" to be
 presented to the VMS help system using library HELPLIB.HLB  in  the
 default  directory.  Note that no spaces are automatically inserted
 between  items.   In  the  preceeding,  /HLPPFX="AIRCRAFT  "  would
 insert the (presumably) required space.

 Activation  of  help by the user will cause the scrolling region to
 be reset and  the  screen  to  be  erased  on  ANSI-compatible  CRT
 terminals.    The   help  is  activated  with  no  default  library
 searching, and prompting and paging do not occur.

 Following the completion of the help  sub-session,  the  prompt  is
 re-issued,  including  any  positioning and screen erase operations
 specified in the command, unless /NOREPROMPT is specified.

 Because the screen may contain  remnants  of  help  text  when  the
 prompt  is  re-issued,  it  is  recommended  that  if /POSITION and
 /HELPLIB are specified together that  /ERASE=EOS  or  /ERASE=SCREEN
 also be specified.

 Use  of  /HELPLIB  implies  /ESCAPE  so  that  the  PF2  key escape
 sequence can be received.  /HELPLIB with /NOESCAPE is pointless.
/HLPPFX=text
 Specifies a string to be prefixed onto any  help  request  text  if
 the  user  terminates  the  response with <PF2> and /HELPLIB=... is
 specified.  If 'text' contains special characters, then  it  should
 be  enclosed  in  double  quotes.   Note that embedded and trailing
 spaces or tabs in 'text' will be significant.
/HLPSFX=text
 Specifies a string to be suffixed onto any  help  request  text  if
 the  user  terminates  the  response with <PF2> and /HELPLIB=... is
 specified.  If 'text' contains special characters, then  it  should
 be  enclosed  in  double  quotes.   Note  that embedded and leading
 spaces or tabs in 'text' will be significant.
/LOCAL_(D)
 Causes all symbol definitions made by the _INQUIRE  command  to  be
 in the local DCL symbol table.  The complement is /GLOBAL.

 /LOCAL is the default.
/LOWER_(D)
/NOLOWER
 /LOWER  permits  the  pass-through  of lower case letters (a..z) in
 the defined string.  If /NOLOWER is specified then all  lower  case
 letters  are  translated  to  upper  case when the result string is
 defined.  This can be useful to avoid having to map a response  for
 comparison purposes to upper case using DCL.

 Note  that  the  /NOLOWER translation is done internally.  If lower
 case letters are entered, they will be echoed that way.
/POSITION=(row,col)
 Causes the terminal's cursor to be positioned to the indicated  row
 and  column before the prompt is issued.  This qualifier has effect
 only for terminals with the ANSI characteristic set.
/PROMPT=string
/NOPROMPT
 Specifies  a  prompt  string,   or   overrides  any  prompt  string
 specification in the second parameter.  /NOPROMPT  specifies a null
 prompt string.  /NOPUNCTUATION is  the  default  when  /NOPROMPT is
 specified.
/PUNCTUATION_(D)
/NOPUNCTUATION
 /NOPUNCTUATION prevents a standard  two  character  sequence  ":  "
 from being appended to the prompt.

 /PUNCTUATION  is  the  default,  unless  /NOPROMPT is specified, in
 which case /NOPUNCTUATION is the default.
/PURGE
/NOPURGE_(D)
 /PURGE  causes  the  terminal  'type-ahead'  buffer  to  be emptied
 before reading the response.

 /NOPURGE is the default.
/REPOSITION
/NOREPOSITION_(D)
 /REPOSITION causes  the  terminal  cursor  position  prior  to  the
 prompt  to  be  saved,  and  subsequently restored to it's original
 position following the response.  This qualifier  has  effect  only
 for terminals with the DEC_CRT attribute set.

 /NOREPOSITION is the default.
/REPROMPT_(D)
/NOREPROMPT
 /REPROMPT   permits   reprompting   after  a  help  operation  (see
 /HELPLIB).

 If  /NOREPROMPT  is  specified,  after  the  help   subsession   is
 completed,  the entered text and the PF2 terminator (<ESC>-O-Q) are
 taken as the response and the _INQUIRE command exits.

 /REPROMPT is the default.
/SECONDS=n
 Specifies a timeout value in seconds for the user to  complete  the
 response  from  the  terminal.  If the response is not completed in
 that time, the command exits with the definition of the symbol  set
 to  all  characters  entered  to that point.  Note that an optional
 target DCL label can be specified for  timeout  with  the  /TIMEOUT
 qualifier.

 The  value  must  be  a  non-negative  integer.  A value of zero is
 legal, and will read the characters in  the  terminal's  type-ahead
 buffer at that point as the symbol's definition.
/TERMINATOR[=symbol]
/NOTERMINATOR_(D)
 /TERMINATOR  with  no  value causes the character(s) that terminate
 input to be returned as a part of the symbol definition.

 /TERMINATOR with a symbol value specification causes  the  response
 terminator  string  to be placed in the given DCL symbol name.  The
 symbol table is determined as described under /GLOBAL and /LOCAL.

 When _INQUIRE is used  non-interactively  with  /TERMINATOR=symbol,
 the named symbol is always set to null.

 /NOTERMINATOR is the default unless /ESCAPE is specified.
/TIMEOUT=label
 Specifies  a  target  DCL  label  for  the  next command if timeout
 occurs (see /SECONDS qualifier).   This  qualifier  has  no  effect
 unless /SECONDS is also given.
!
/TRMCHARS=[(option[,option2])]
/NOTRMCHARS_(D)
 /TRMCHARS specifies the terminator characters that will end the read
 operation.  If  not  specified,  this  defaults  to the standard VAX
 terminal read terminator set.

 If  /TRMCHARS  is  given  with  no  options,  then there are no read
 terminators, and the read only terminates when  the  buffer  is full,
 or  when  an  I/O  exception, such  as timeout or bad escape sequence

 /TRMCHARS can also have either or both of two options:

 CHARACTERS=string   This  indicates  that the characters given in the
                     string are terminators for the read operation.

 CONTROL=string      This indicates that the control-analogues of  the
                     characters in  the  string  are terminators.  The
                     control-analogue  of  a  character is its decimal
                     ASCII representation less decimal 64.
2 Program_Interface
 It  is  possible  for  an  application  program to call the INQUIRE
 routines to perform  the  same  sorts  of  processing  that  a  DCL
 _INQUIRE  command  can  specify.   There  are two methods for doing
 this.  The command interface is called with a command string  in  a
 format  similar  to  that  of the corresponding DCL command.  While
 very simple to use, it requires processing overhead  to  parse  the
 command string on each call.

 The  direct  call  interface  is  not  quite as simple, but is more
 efficient, especially if many calls are to be made.

 All routines are available  by  linking  with  the  object  library
 SYS$ENVROOT:[INQUIRE]INQUIRE.OLB.
3 Command_Interface
 The command call statement has the form:

     Status.wlc.v = INQ$PROGRAM(cmdstr.rt.ds, result-str.wt.ds,
                          result-len.wl.r)

 Cmd-str  is  a  string containing a command line as it would appear
 for _INQUIRE, including  all  necessary  qualifiers.   The  command
 string should NOT contain the "_INQUIRE" prefix itself.

 The  response string is returned right blank-padded or truncated if
 necessary in result-str.  The actual  length  of  the  response  is
 returned in result-len.

    Example:

     o ISTAT=INQ$PROGRAM('SYS$COMMAND "Value"/SECONDS=4',RES,LEN)


 Note  that  certain  qualifier  forms  are invalid when used in the
 program interface.  Their  appearance  causes  a  fatal  status  of
 CLI$_INVQUAL  to  be  returned  as  the  status of the call.  These
 qualifiers are:
  
    /DEVICE=name
    /EOF=label
    /GLOBAL
    /LOCAL
    /TERMINATOR=symbol
    /TIMEOUT=label
  
3 Direct_Call
 The INQUIRE direct call interface provides several entry points  to
 specify  the  options  for the inquiry.  The prompting is always to
 SYS$COMMAND with this  method.   /NOTERMINATOR  and  /NOPUNCTUATION
 are  always in effect. However, note that the terminator string can
 always be picked up with a call to a separate entry point.

 To use this method, first issue a  call  to  INQ$CALL_INIT  in  the
 form:

                   Status.wlc.v = INQ$CALL_INIT()

 Then  call  one  or more of the optional set-up routines if special
 options are desired (see below).  Then, issue one or more calls  to
 INQ$CALL_READPROMPT of the form:

   Status.wlc.v = INQ$CALL_READPROMPT(flags.wl.r,prompt-str.rt.ds,
               response-str.wt.ds, response-len.wl.r,

 Each call to INQ$CALL_READPROMPT issues a inquiry to SYS$COMMAND.

 The  flags argument specifies call-specific processing options (see
 below).  The prompt-str, response-str  and  response-len  arguments
 are all as described for the command interface  method  above.  The
 length of response-str is taken as the implied value of /BUFLEN.
4 Flags
 The  flag  bits  given in a call to INQ$CALL_READPROMPT are defined
 for  Fortran   users   in   SYS$ENVROOT:[INQUIRE]INQCALFOR.DEF   as
 follows:
  
       Name            Value    Description
  
 INQ$M_FLAG_NOECHO       1      Set for /NOECHO
 INQ$M_FLAG_NOET         2      Set for /NOET
 INQ$M_FLAG_PURGE        4      Set for /PURGE
 INQ$M_FLAG_REPOSITION   8      Set for /REPOSITION
 INQ$M_FLAG_NOREPROMPT  16      Set for /NOREPROMPT
 INQ$M_FLAG_NOLOWER     32      Set for /NOLOWER
 INQ$M_FLAG_NOESCAPE    64      Set for /NOESCAPE
  
4 INQ$CALL_DEVICE}
 Status.wlc.v = INQ$CALL_DEVICE(device.rt.ds)

 Set  the  device  name  to  be  used for  read - prompting, as with
 /DEVICE=name.
4 INQ$CALL_ERASE
 Status.wlc.v = INQ$CALL_ERASE(code.rl.r)

 Call  this  routine before any call to INQ$CALL_READPROMPT to cause
 the   screen   to   be   erased   before   the   prompt   as   with
 /ERASE=erase-item.   The  given code determines the type of erasing
 performed.       These       codes       are       defined       in
 SYS$ENVROOT:[INQUIRE]INQCALFOR.DEF as follows:
  
       Name           Value            Description
  
 INQ$C_ERASE_EOL        1          Erase to end of the line
 INQ$C_ERASE_EOS        2          Erase to end of the screen
 INQ$C_ERASE_LINE       3          Erase entire line
 INQ$C_ERASE_SCREEN     4          Erase entire screen
  
 The  effect  of  this  call  persists  until it is called again, or
 until it is reset by calling INQ$CALL_INIT.
4 INQ$CALL_POSITION
 Status.wlc.v = INQ$CALL_POSITION(row.rl.r,column.rl.r)

 Call this routine before any call to INQ$CALL_READPROMPT  to  cause
 the    initial    cursor    position    to    be    set   as   with
 /POSITION=(row,column).

 The effect of this call persists  until  it  is  called  again,  or
 until it is reset by calling INQ$CALL_INIT.
4 INQ$CALL_GETTERM
 Status.wl.v = INQ$CALL_GETTERM(term-str.wt.ds,term-len.wl.r)

 This   routine   returns   the  terminator  and  terminator  length
 associated  with  the  last  response  returned  with  a  call   to
 INQ$CALL_READPROMPT.   The  terminator  string  is  returned  right
 blank-padded,  truncated  if  necessary.   Term-len  contains   the
 actual  length  of  the  terminator string that was received in the
 response.
4 INQ$CALL_TIMEOUT
 Status.wl.v = INQ$CALL_TIMEOUT(seconds.rl.r)

 Call this routine before any call to INQ$CALL_READPROMPT  in  order
 to  cause  the  read  to  have a integer timeout value of the given
 number of seconds as with /TIMEOUT=seconds.

 The effect of this call persists  until  it  is  called  again,  or
 until it is reset by calling INQ$CALL_INIT.
4 INQ$CALL_TRMCHARS
 Status.wlc.v = INQ$CALL_TRMCHARS(array.rb.r)

 Call this routine to pass explicit read terminators.  The given array
 must  be a 32 byte (256 bit) mask array.  Bit position "i" represents
 the character  code  with ASCII value "i".  If set, the corresponding
 character is a terminator.

 Given a 32-byte FORTRAN  array  with the name, say, "MASK", initially
 zeroed, it is a simple matter to  set  a  bit  "i" in MASK, using the
 library routine LIB$INSV.

 The  call  to  set  the  character "A" as a terminator in "MASK", for
 example, would be:

          CALL LIB$INSV(1,ICHAR('A'),1,MASK)

 Several such calls can be made to set several bits of a mask.

 The effect  of  this call persists  until  it  is  called  again,  or
 until it is reset by calling INQ$CALL_INIT.
4 Sample_Program
 There  follows  below  an example program of the use of the INQUIRE
 call interface, written in Fortran.

 	PROGRAM INQUIRE_CALL_DEMO
 C
 C	This program demonstrates the use of the INQUIRE program
 C	call interface.  It loops until the user hits a terminator
 C	key on the terminal (<return>, control key, etc.) and then
 C	calls routine ACTION with the terminator key that was struck
 C
 	IMPLICIT NONE
 	INCLUDE 'SYS$ENVROOT:[INQUIRE]INQCALFOR.DEF/NOLIST'
 C
 C	Functions
 C
 	INTEGER INQ$CALL_INIT, INQ$CALL_TIMEOUT, INQ$CALL_READPROMPT
 C
 C	Local store
 C
 	CHARACTER RESP, TERM
 	INTEGER NULL(2) /2*0/ !Fake-out null string descriptor
 	INTEGER MS100(2) /-1000000,0/ !100 millisecss in delta time
 	INTEGER ISTAT, TLEN, RLEN
 C
 C	Initialize the call interface
 C
 	ISTAT=INQ$CALL_INIT()
 	IF (.NOT. ISTAT) CALL EXIT(ISTAT)
 C
 C	Set the timeout for zero seconds
 C
 	ISTAT=INQ$CALL_TIMEOUT(0)
 	IF (.NOT. ISTAT) CALL EXIT(ISTAT)
 C
 C	Loop here until a terminator is hit on the terminal
 C
 	TLEN=0
 	ISTAT=1
 	DO WHILE ((TLEN .EQ. 0) .AND. ISTAT)
 	  ISTAT=INQ$CALL_READPROMPT(INQ$M_FLAG_NOECHO,NULL,RESP,RLEN)
 	  CALL INQ$CALL_GETTERM(TERM,TLEN)
 	  CALL SYS$SETIMR(,MS100,,)
 	  CALL SYS$WAITFR()
 	ENDDO
 	IF (.NOT. ISTAT) CALL EXIT(ISTAT)
 C
 C	Call routine now that user has hit terminator key
 C
 	CALL ACTION(TERM)
 	END
