When a program runs, you can pass information to it in several ways:
The PULL instruction is one way for a program to receive input. Repeating an earlier example shows this. Here is how to call the ADDTWO program:
REXX addtwo
Here is the ADDTWO program.
/**************************** REXX ******************************/
/* This program adds two numbers and produces their sum. */
/****************************************************************/
PULL number1
PULL number2
sum = number1 + number2
SAY 'The sum of the two numbers is' sum'.'
The PULL instruction can extract more than one value at a time from the terminal by separating a line of input. The following variation of the example shows this.
REXX addtwo 42 21
/**************************** REXX ******************************/
/* This program adds two numbers and says their sum */
/****************************************************************/
PULL number1 number2
sum = number1 + number2
SAY 'The sum of the two numbers is' sum'.'
The PULL instruction extracts the numbers 42 and 21 from the terminal.
Another way for a program to receive input is through values you specify when you call the program. For example to pass the two numbers 42 and 21 to a program named ADD, you could use the CICS command:
REXX add 42 21
The program ADD uses the ARG instruction to assign the input to variables as shown in the following example.
/**************************** REXX ******************************/
/* This program receives two numbers as input, adds them, and */
/* produces their sum. */
/****************************************************************/
ARG number1 number2
sum = number1 + number2
SAY 'The sum of the two numbers is' sum'.'
ARG assigns the first number 42, to number1, and the second number 21, to number2.
If the number of values is fewer or more than the number of variable names after ARG or PULL, errors can occur, as the following sections describe.
If you specify fewer values than the number of variables after PULL or ARG, the extra variables are set to the null string. Here is an example in which you pass only one number to the program:
REXX add 42
The language processor assigns the value 42 to number1, the first variable following ARG. It assigns the null string to number2, the second variable. In this situation, the program ends with an error when it tries to add the two variables. In other situations, the program might not end in error.
When you specify more values than the number of variables following PULL or ARG, the last variable gets the remaining values. For example, you pass three numbers to the program ADD:
REXX add 42 21 10
The language processor assigns the value 42 to number1, the first variable following ARG. It assigns the value 21 10 to number2, the second variable. In this situation, the program ends with an error when it tries to add the two variables. In other situations, the program might not end in error.
To prevent the last variable from getting the remaining values, use a period (.) at the end of the PULL or ARG instruction.
ARG number1 number2 .
The period acts as a dummy variable to collect unwanted extra information. (In this case, number1 receives 42, number2 receives 21, and the period ensures the 10 is discarded. If there is no extra information, the period is ignored. You can also use a period as a placeholder within the PULL or ARG instruction as follows:
ARG . number1 number2
In this case, the first value, 42, is discarded and number1 and number2 get the next two values, 21 and 10.
Like the PULL instruction, the ARG instruction changes alphabetic characters to uppercase. To prevent translation to uppercase, use PARSE ARG as in the following example.
/**************************** REXX ********************************/
/* This program receives the last name, first name, and score of */
/* a student and reports the name and score. */
/******************************************************************/
PARSE ARG lastname firstname score
SAY firstname lastname 'received a score of' score'.'
The left column shows the input values sent to a program. The right column is the ARG instruction within the program that receives the input. What value does each variable receive?
ANSWERS
Values passed to a program are usually called arguments. An argument can consist of one word or a string of words. Blanks separate words within an argument from each other. The number of arguments passed depends on how the program is called.
When you call a REXX program using either the CALL instruction or a REXX function call, you can pass up to 20 arguments to the program. Separate each argument from the next with a comma.
For more information about functions and subroutines, see Writing Subroutines and Functions. For more information about arguments, see section Parsing Multiple Strings as Arguments.