Category : Batch File Utilities - mostly for DOS
Archive   : INPUT16.ZIP
Filename : INPUT.DOC

INPUT Ver. 1.6
(c) Copyright 1986,1990
William C. Parke
Washington, D.C.

INPUT is a batch file utility to get console input from
within a batch file. There are several variants of this type of
program in the public domain. A common type uses the ERRORLEVEL
to pass a keyboard response to a BAT file. These types are
limited to a single key transfer. Another type, such as ANSWER,
written by Frank Schweiger, prompts for a console input, then
puts the result into an Environment Variable. INPUT is of this
type, but adds some refinement. With INPUT, the response string
is set to upper case unless the 'bare' switch is used. A
linefeed is sent to the console after the response to allow a
following ECHO command. In addition, preceding and trailing
blanks are removed in the default mode. Another option lets the
BAT file define the length of the string used in the response.

Acknowledgement: My thanks to Douglas Clark for his considerable
influence on the design and development of this program.

INPUT is released to the public domain. The author retains
copyright. The program may be freely distributed, provided no
profits ensue from such distribution. INPUT may not be packaged
with any commercial product without expressed permission from the
author.

Syntax:

The syntax for INPUT is the following:

INPUT prompting string [/b/p/q/f[a]/nn]

Output of this program is placed into an Environment Variable
called ANS. If there is no space left in the Environment, the
ERRORLEVEL is set to 1. If a previous ANS is found, it is
removed and the new ANS is placed at the end of the Environment
Variable list. If there is no response to the INPUT prompt,
ERRORLEVEL is set to 1. The prompting string may contain any
standard ASCII characters except the dollar sign and the slash
'/' character. This string is displayed on the console as soon
as INPUT in invoked. If no string is present, a help display for
the use of INPUT is displayed. The brackets above enclose the
optional switches and parameters. The switches may be used in any
combination.

Optional switches:

The optional switches are defined as:

b = bare input

p = put answer in parent environment

q = quiet mode: typed characters obscured by *'s

nn = a truncation number from 1 to 72

f[a] = fill ANS [with character a] to make length nn

If the 'b' switch is used, then the console response string is
left as typed and inserted into the Environment as the variable
ANS. Without the 'b' option, a response string is converted to
upper case, and any preceding or trailing spaces are removed.

The 'p' switch makes INPUT put the variable ANS in all copies of
the environments (for parent and child processes). This is
necessary when INPUT is run after 'shelling' out of another
program, thus loading another COMMAND processor with its own copy
of the original environment. If the variable ANS is to survive
even after exiting the shell, the parent environments must also
be changed to show the new variable.

Before starting a program shell, a second COMMAND process, or a
child process, it may be necessary to expand the original parent
environment so that the inherited child environment will be large
enough to contain the ANS variable. This is easily done using
using:

SET ANS=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

as a DOS command under the original COMMAND processor, where
'xxx' is made long enough to contain any anticipated answers to
an INPUT query.

INPUT may be used in batch files run from a program shell, a
second COMMAND processor, or from a child process. In these
circumstances, only the environment of the child process will be
used for storing the ANS variable, unless the /p switch is used
on the INPUT command line. In the latter case, the original
parent environment will be used to store ANS. This may be
desirable if the new variable is to survive after the child
process is terminated.

If INPUT is used to take a user password, the 'q' switch will set
INPUT into quiet mode, i.e. the user's keystrokes will not be
echoed onto the screen. Instead, each keystroke will show as an
asterisk. Since the received password will be placed in the
environment variable ANS, the batch file should take the
precaution of deleting ANS before finishing. (The syntax: SET
ANS= with no text following the equal sign clears the variable.)

If the 'nn' truncation number is given, the console response
string will be truncated or space filled to length nn before
being used to define ANS. This option is useful for insuring that
a variable with a fixed length field is properly defined, or that
a potentially ambiguous answer is limited. This makes response
testing easier in batch files. For example, a yes-no question
could generate responses of Yes, YES, yes, No, NO, no, etc.
However, using the switch /1 makes ANS=Y or ANS=N. If the user
attempts to type an answer beyond the defined field, i.e. more
characters than the truncation number, a beep will sound.

The 'f' switch is used in conjunction with the truncation number
nn to make the variable ANS have a fixed record length specified
by nn. If the answer is shorter than nn, it will be filled with
spaces to the given length. NOTE: the display of SET variables
will not show the length of trailing blanks. Never-the-less, the
trailing blanks are present. By following the 'f' switch with a
valid ASCII character, the variable will be end-filled with this
character. If /f is given without /nn, then the default value
for nn is 8. If the /f is followed by another character (e.g.
/f! ), then that character will be used to fill the ANS variable
to fixed length.

Function Key Input:

If the user types a function key by itself, the ESC key, or the
TAB on an IBM PC keyboard, then INPUT creates a special ANS,
containing a triplet code giving a mneumonic for the key. The
first will be an 'at' sign (@) to signify an extended key has
been pressed. The second and third characters are determined by
the correspondence shown in Appendix I. For example, pressing F1
produces '@f1'.

Keypad Line Edit Feature:

The keypad keys, if typed before any other normal key, will also
produce a special ANS variable in the environment, as shown in
the Appendix I. However, if the left arrow key, right arrow key,
Insert key, or Delete key are typed after some screen input has
already been entered (but not terminated with a carriage return),
then these keys will function as editing keys.


Example fragments from batch file applications:

Example 1: Getting yes/no answers:

IF EXIST %1 GOTO OK
INPUT %1 not found. Do you wish to go on? /1
IF %ANS%==Y GOTO OK
GOTO EXIT
:OK
...
:EXIT
SET ANS=

The last line of this example drops ANS from the Environment,
saving space for additional variables.

Example 2: Getting new path and file names:

INPUT Give new file name:
SET FILE=%ANS%
IF EXIST %FILE% GOTO BEGIN
SET ANS=
...

Note: A space should be added at the end of the colon above.

Example 3: Starting a requested program:

ECHO OFF
:START
TYPE PROGS.LST
REM PROGS.LST is an ascii list of programs
INPUT Enter program and command line, if needed :
IF ERRORLEVEL=1 GOTO EXIT
%ANS%
IF NOT ERRORLEVEL=1 GOTO EXIT
ECHO Program error.
ECHO Please re-enter or type a carriage return.
GOTO START
:EXIT
SET ANS=

Note that the user can exit this BAT by typing a carriage
return in response to the INPUT string. Alternatively, CTRL-
C can be used for the same purpose.

Example 4: Using a function key response:

ECHO OFF
DISPLAY MENU
REM DISPLAY is a special program for displaying text
INPUT Press the function key for your choice. /0
IF %ANS%==@f1 GOTO LABF1
IF %ANS%==@f2 GOTO LABF2
...
:LABF1
...
:LABF2
...

(The program, DISPLAY by W. C. Parke and Doug Clark, can be
used to replace TYPE for a far more rapid display of text. It
also can be used to generate color and special attributes
from an ordinary ASCII text file.)

Example 5: Creating a fixed length variable:

ECHO OFF
INPUT What is the record name? /f./10
...

The variable ANS will be ten characters long, starting with
the user's input, and filled with the period character.


Appendix I:

Selected List of IBM Extended Keyboard Codes Returned in ANS

normal shift contrl alt Keypad keys:

F1 - @f1 @s1 @c1 @a1 Lft- @Lf
F2 - @f2 @s2 @c2 @a2 Rgt- @Rt
F3 - @f3 @s3 @c3 @a3 Up - @Up
F4 - @f4 @s4 @c4 @a4 Dwn- @Dn
F5 - @f5 @s5 @c5 @a5 PgD- @Pd
F6 - @f6 @s6 @c6 @a6 PgU- @Pu
F7 - @f7 @s7 @c7 @a7 Hom- @Ho
F8 - @f8 @s8 @c8 @a8 End- @En
F9 - @f9 @s9 @c9 @a9 Ins- @In
F10- @f0 @s0 @c0 @a0 Del- @De

Special Control code returns:

ESC- @Es TAB- @Tb

Appendix II:

ERRORLEVEL Returns from INPUT:

0 No error
1 No valid response from user to INPUT query
2 Insufficient environment space
3 No environment found
4 Child environment not large enough, but parent was


Appendix III:

Version History:

1.6 October, 1990

Added line editor features: If any input is present,
then the left and right arrow keys move the cursor
as expected; also Insert and Delete keys as edit keys.

Enforced truncation number on user input.

1.5 August, 1990

Translated function and keypad keys into mneumonic forms.
Dropped /i switch; extended keys, ESC, and TAB now can be
typed during ordinary key input.

1.4 July, 1990

Added support for IBM function and cursor keys with /i
switch. Added variable fill character.

1.3 December, 1988

Added /q switch for quiet password input.

1.2 July, 1988

Added /f switch to fill ANS with spaces to have a fixed
record length. Also, added code to make /p switch insert ANS
in all environments from the original to the latest child.
Added new ERRORLEVEL returns.

1.1 August, 1988

Modified INPUT to use the child environment by default. The
/p switch is used to force INPUT to use the original parent
environment for storing ANS.

1.0 September, 1986

Initial release.