1 Getinput

  Getinput is a replacement for INQUIRE and/or "READ SYS$COMMAND"
  Commonly used options in DCL routines, can be handled by Getinput.
  Getinput reads user input from SYS$COMMAND and returns the given 
  OutputSymbol with this input. Getinput is able to compare the 
  input to given valid answers. Options as echo/noecho and timeout 
  are also available.


  Format:  GETINPUT OutputSymbol 


  Output: 
 
  1. Getinput returns the given input into the given OutputSymbol.

  2. Getinput creates a status symbol GETINPUT_STATUS:

  SUCCES     Getinput has ended successfully
  CTRLZ      The userinput was CTRL-Z
  TIMEOUT    The user did not give any userinput within the timeout period
  ERROR      Getinput ended with errors
  TRUNCATED  Getinput has ended successfully, but the input is truncated

2 Parameter

  Getinput has one parameter, the OutputSymbol to receive the userinput. 
  This parameter is required except for /RESET and /ENTER.

2 Special_input_characters

  The user can use two special characters to perform certain functions:

  ?     to get help information about the input format.
  #     to create a subprocess to execute DCL commands.

3 Examples

  $ GETINPUT OutputSymbol /TYPE=INTEGER/DEFAULT=5/PROMPT="Geef een getal"
  Geef een getal [5]: #
  %GIP-I-SPAWNED> show time
    24-NOV-2006 11:25:40
  %GIP-I-SPAWNED> logo
    Process TEST_2 logged out at 24-NOV-2006 11:25:43.43
  Geef een getal [5]: # show time
    24-NOV-2006 11:25:46
  Geef een getal: 12

  $ GETINPUT OutputSymbol /TYPE=INTEGER/DEFAULT=5/PROMPT="Geef een getal"
  Geef een getal [5]: ?
  %GIP-I-HELP, the input must be an integer value
  Geef een getal [5]: 34

2 /RESET

  /RESET

  Getinput saves settings as facility, so there is no need to specify
  these settings every time getinput is called.
  To reset these settings to the default value use /RESET.

2 /DEFAULT

  /DEFAULT="default value"

  When a default value is needed, use /DEFAULT. When the user hits 
  the ENTER key, without input, the default value will be assigned
  to <OutputSymbol>. The default value will be included in the 
  prompt string between "[" and "]", see /PROMPT.

2 /PROMPT

  /PROMPT="Prompt string"

  When no prompt string is specified, the prompt will be ": ".
  To use your own prompt, use /PROMPT="String". When a default value
  is given, this will be placed into the prompt string.

3 Example

  $ GETINPUT OutputSymbol /PROMPT="Enter a value between 0-10"/DEFAULT=5

  The prompt will be:

  Enter a value between 0-10 [5]:  

2 /FACILITY

  /FACILITY=String

  Every OpenVMS message has a facility prefix. To use your own, 
  use /FACILITY="Facility string" at the Getinput command line.
  The current facility string will be saved in a logical, so you
  need to set the facility prefix only once. To reset to the default
  facility GIP use /RESET.

3 Example

  The default facility prefix for Getinput is "GIP". So when the 
  following command is given, you get an error message.

  $ GETINPUT OutputSymbol /TYPE=INTEGER/DEFAULT=test
  %GIP-F-DEFERR, default has to be numeric

  $ GETINPUT OutputSymbol /TYPE=INTEGER/DEFAULT=test/FACILITY=MYOWN
  %MYOWN-F-DEFERR, default has to be numeric

2 /TYPE

  /TYPE=INTEGER

  When the user is only allowed to enter an integer as answer, 
  use /TYPE=INTEGER. The user is then prompted for an integer answer.

  /TYPE=DATE

  When the user is only allowed to enter a valid OpenVMS date 
  as answer, use /TYPE=DATE. The user is then prompted for a date 
  as answer.

  As input TODAY, TOMORROW and YESTERDAY are also accepted.

  /TYPE=FILE

  When the user is only allowed to enter a valid OpenVMS file
  specification as answer, use /TYPE=FILE. The user is then prompted 
  for a valid file specification.

3 Examples

  $ GETINPUT OutputSymbol /TYPE=INTEGER/PROMPT="Enter an integer"
  Enter an integer: test
  %GIP-W-INPERR, input has to be numeric
  Enter an integer: 6
  $ show symbol OutputSymbol
    OUTPUTSYMBOL = "6"

  (Getinput always returns a string symbol, even with /TYPE=INTEGER)

  $ GETINPUT OutputSymbol /TYPE=DATE/PROMPT="Enter start date"
  Enter start date: test
  %GIP-W-IVATIME, invalid absolute time - use DD-MMM-YYYY format
  Enter start date: tomorrow
  $ show symbol OutputSymbol
    OUTPUTSYMBOL = "24-NOV-2006"

  $ GETINPUT OutputSymbol /TYPE=FILE/PROMPT="Give output file"
  Give output file: & 
  %GIP-W-NOFILE, no valid file specification given
  Give output file: test.log
  $ show symbol OutputSymbol
    OUTPUTSYMBOL = "test.log"

2 /VALID

  /VALID=(val1,val2...)

  Getinput can compare the user input to valid possibilities specified 
  with /VALID.

  Options are:

  /VALID=(str1,str2,str3)       As user input only the valid 
                                strings are accepted. When the 
                                user input is unique, only the 
                                unique part is needed, see examples.
  /VALID=(2,4,6)                As user input only the strings 
                                2, 4 and 6 are accepted.
  /VALID=(1,10)                 As user input only the strings 
                                1 and 10 are accepted.    
  /VALID=(1,10)/TYPE=INTEGER    As user input an integer from 
                                1 to 10 is accepted.
  /VALID=(1,10)/TYPE=INT/NORANG As user input the integers 1 and 10 
                                are accepted.
 
3 Examples

  $ GETINPUT OutputSymbol /VALID=(yes,no)/PROMPT="Continue"
  Continue: JA
  %GIP-W-INPERR, input has to be in the VALID list
  Continue: ?
  %GIP-I-HELP, the input must be chosen from the following list: YES,NO
  Continue: y
  $ show symbol OutputSymbol
    OUTPUTSYMBOL = "YES"

  $ GETINPUT OutputSymbol /VALID=(1,5)/TYPE=INT/PROMPT="Kies een optie"
  Kies een optie: 0
  %GIP-W-INPERR, input has to be in the VALID list
  Kies een optie: yes
  %GIP-W-INPERR, input has to be numeric
  Kies een optie: ?
  %GIP-I-HELP, the input must be an integer value from 1 to 5
  Kies een optie: 5
  $ show symbol OutputSymbol
    OUTPUTSYMBOL = "5"

2 /RANGE

  /RANGE
  /NORANGE

  When /TYPE=INTEGER and /VALID are used together, you see the following 
  options:

  $ GETINPUT OutputSymbol /VALID=(1,5)/TYPE=INTEGER

    In this example, OutputSymbol may have a value from 1 util 5.
    When there only two integers in the valid list, /RANGE is default.

  $ GETINPUT OutputSymbol /VALID=(2,4,6)/TYPE=INTEGER

    In this example, OutputSymbol may have the value 2, 4, or 6.
    When there are more than two integers in the valid list, /NORANGE 
    is default.

  So when the following is needed,

  $ GETINPUT OutputSymbol /VALID=(2,4)/TYPE=INTEGER 

  and you want OutputSymbol to be 2 or 4, use /NORANGE to tell this 
  to GETINPUT.

2 /LINE

  /LINE=(PROMPT=n,MESSAGE=n)

  To position the prompt string on a fixed line on the screen 
  use /LINE. PROMPT=n, positions the prompt string on the
  given line, and MESSAGE=n, positions the GETINPUT messages on 
  the given line, When message is not specified, the message
  position will be directly below the prompt string.

2 /LENGTH

  /LENGTH=(Minimum length,Maximum length)
  or
  /LENGTH=Fixed length

  When the user is requested to give a string or an integer with
  a fixed, or specified length, use /LENGTH

3 Example

  $ GETINPUT OutputSymbol /LENGTH=(8,12)/PROMPT="Enter a password"
  Enter a password: thisisatestpassword
  %GIP-W-LENERR, input is more than maximum length
  Enter a password: thisis
  %GIP-W-LENERR, input is less than minimum length
  Enter a password: thisisatest
  $ show symbol OutputSymbol
    OUTPUTSYMBOL = "thisisatest"

  $ GETINPUT OutputSymbol /LENGTH=(1,2)/TYPE=INTEGER/PROMPT="What value"
  What value: 123
  %GIP-W-LENERR, input is more than maximum length
  What value: 56
  $ show symbol OutputSymbol
    OUTPUTSYMBOL = "56"

2 /TRUNCATE

  /TRUNCATE=confirm (Default)
  /TRUNCATE=noconfirm

  Truncate can only be used together with /LENGTH.
  When the given input is to large, it will be truncated to
  the maximum length. /TRUNCATE=noconfirm will truncate
  without asking, but the symbol GETINPUT_STATUS will be 
  set to TRUNCATED.

3 Example

  $ GETINPUT OutputSymbol /LENGTH=(8,12)/TRUNCATE/PROMPT="Enter a password"
  Enter a password: thisisatestpassword
  Input is to long, truncate to "thisisatestp" (Yes,No,Quit) <Yes>: N
  Enter a password: thisisatestpassword
  Input is to long, truncate to "thisisatestp" (Yes,No,Quit) <Yes>: 
  $ show symbol OutputSymbol
    OUTPUTSYMBOL = "thisisatestp"

  $ GETINPUT OutputSymbol /LENGTH=(8,12)/TRUNCATE=NOCONFIRM -
                          /PROMPT="Enter a password"
  Enter a password: thisisatestpassword
  %GIP-I-TRUNC, input truncated to thisisatestp
  $ show symbol OutputSymbol
    OUTPUTSYMBOL = "thisisatestp"
  $ show symbol getinput_status
    GETINPUT_STATUS = "TRUNCATED"

2 /LANGUAGE

  /LANGUAGE=Message language

  Default all the messages are given in English. To get them in an 
  other language, use /LANGUAGE.

  Valid languages are DUTCH, NEDERLANDS or ENGLISH

2 /ENTER

  /ENTER

  Using /ENTER is a short for the following command:

  $ GETINPUT /PROMPT="Hit ENTER to continue" 
  short
  $ GETINPUT/ENTER

  or

  $ GETINPUT /PROMPT="Geef ENTER om verder te gaan"/DUTCH
  short
  $ GETINPUT/ENTER/DUTCH

2 /UPPERCASE

  /UPPERCASE

  To return the given input always in uppercase use /UPPERCASE.
  Default the case is preserved.

2 /ECHO

  /ECHO (default)
  /NOECHO

  Controls whether the terminal displays the input it receives.
  With the /NOECHO qualifier, the terminal does not displays the
  user input.

  Use /NOECHO to suppress the user input on the terminal

  (/NOECHO and /TRUNCATE cannot be used together)

2 /TIMEOUT

  /TIMEOUT=Timeout value (in seconds)

  When the user does not give input, Getinput will terminate after 
  the given timeout value and the symbol GETINPUT_STATUS will be set
  to TIMEOUT.