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
1 – 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.
2.1 – 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
3 /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.
4 /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.
5 /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.
5.1 – Example
$ GETINPUT OutputSymbol /PROMPT="Enter a value between 0-10"/DEFAULT=5 The prompt will be: Enter a value between 0-10 [5]:
6 /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.
6.1 – 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
7 /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.
7.1 – 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"
8 /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.
8.1 – 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"
9 /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.
10 /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.
11 /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
11.1 – 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"
12 /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.
12.1 – 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"
13 /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
14 /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
15 /UPPERCASE
/UPPERCASE To return the given input always in uppercase use /UPPERCASE. Default the case is preserved.
16 /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)
17 /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.