Obtaining Input

Identifying Parameters

PARM statements can be inserted in a command file or UDC to define parameter data that is entered when the command file or UDC is issued. The following example shows the command input to invoke the FILINFO command file. The file name A is provided when the command file name is issued.

   FILINFO A

If parameter data is desired, one or more PARM statements can be included in the command file. For UDCs, parameters can be defined using the UDC name line, PARM statements, or both. Each entry defines one or more required or optional parameters. The following example defines the parameter input, a file name, in a PARM statement. The subsequent FINFO statement uses the parameter value to verify the existence of the named file. Note that a parameter must be explicitly dereferenced in all commands and expressions.

   PARM FNAME

   IF NOT (FINFO("!FNAME","EXISTS")) THEN

   [vellip]

In this example, the file name is a required parameter since no default value has been provided for the parameter field. In processing the command file, the file name is inserted in any expression where the parameter FNAME is dereferenced, such as in the FINFO statement.

	NOTE: Parameters must be accessed by explicit dereferencing. Implicit dereferencing will result in either a message stating that the variable does not exist or insertion of a variable value of the same name.

Parameter data is optional if a default value is provided in the PARM statement or UDC name line. The following example of the LIST command file defines six parameters and supplies default values for five of them. Note that the two PARM statements are used to differentiate between required and optional parameters.

   PARM F1

   PARM F2=$NULL,F3=$NULL,F4=$NULL,F5=$NULL,F6=$NULL

This example allows up to six file names to be entered when the command file is invoked. The first file name is the only required parameter. The value $NULL is substituted as the default value for the optional parameters. The following example shows how the LIST command file could be invoked.

   LIST A,B,C

Each of the three parameters is matched with its associated parameter name. The file name A is identified as F1, the first parameter. File name B is F2, and file name C is F3. Because no other parameters were supplied in the call, F4, F5, and F6 contain the default value $NULL. This method of coding is often used in looping constructs to provide input to multiple iterations of a process with a single invocation.

In a UDC, parameter data can be specified in two ways. Parameters can be defined in the UDC header on the line containing the UDC name, as shown in the following example.

   LIST F1,F2=$NULL,F3=$NULL,F4=$NULL,F5=$NULL,F6=$NULL

Parameters can also be entered on the line after the UDC name and identified by the PARM keyword, as in command files.

   LIST

   PARM F1,F2=$NULL,F3=$NULL,F4=$NULL,F5=$NULL,F6=$NULL

Note that both of these methods can be used within a single UDC, as shown in the following example.

   LIST F1

   PARM F2=$NULL,F3=$NULL

   PARM F4=$NULL,F5=$NULL,F6=$NULL

Prompting for Input

The INPUT command prompts the user for input data and reads user input from $STDIN, the user's terminal, into a defined variable. The data received with the INPUT command is considered string, even if it consists of numeric data.

The INPUT command allows three parameters. The first parameter specifies the variable name for the input data. The second specifies a character string to be used as the prompt. The length of time allowed for the user to enter input data can be specified by entering a third parameter.

In the following example, the echoed statements and the prompt for the user's selection create a menu of run variations. The user's selection at the prompt triggers a branch to the appropriate routine.

   ECHO Enter 0 to exit.

   ECHO       1 to review database.

   ECHO       2 to update database.

   INPUT CHOICE,"Which number do you select?",15

In the preceding example, the options in the ECHO commands and the prompting phrase from the INPUT command are displayed at the user's terminal. The variable, CHOICE, receives the user's response, to be analyzed in later processing. Fifteen seconds (,15) specifies the length of time to wait for a reply.

Retrieving Input from a File

By using redirection indicators, most CI statements can retrieve input from a file rather than from parameter data or direct user input. The name of the file containing the input data is preceded by the redirection indicator for input (<) and added to the appropriate statement. Only a single file name can be specified for input redirection; wildcard characters, therefore, cause errors. The following example shows how the editor is invoked and its input file specified in a single statement.

   :EDITOR <INSFILE

When input is redirected, the file must exist. Unless otherwise specified in a file equation, the CI searches for a TEMP file first, then a permanent file. By default, it opens the file for read and share access. These defaults can be overridden by using a backreference to a file equation.

Redirection supports HFS (hierarchical file system) names. ECHO Hi There! >> ./somefile appends to the file ./somefile

The following example receives processing input by redirecting the INPUT command's source from the user's terminal to a file named INFILE. The first record of INFILE is read into the variable named RECORD.

   INPUT RECORD <INFILE

Because of possible confusion with the less than (<) character, redirection cannot be performed with the IF, WHILE, CALC, SETVAR, REMOTE, or COMMENT statements. All other CI statements can perform input redirection.