Passing Information to a program

When a program runs, you can pass information to it in several ways:

Getting Information from the Program Stack or Terminal Input Device

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.

Figure 7. Example of a program That Uses PULL
/**************************** 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

Figure 8. Variation of an Example that Uses PULL
/**************************** 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.

Specifying Values When Calling a program

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.

Figure 9. Example of a program That Uses the ARG Instruction
/**************************** 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.

Specifying Too Few Values

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.

Specifying Too Many Values

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.

Preventing Translation of Input to Uppercase

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.

Figure 10. Example of a program That Uses PARSE ARG
/**************************** 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'.'

Exercises - Using the ARG Instruction

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?

Input
Variables Receiving Input
1. 115 -23 66 5.8
ARG first second third
2. .2 0 569 2E6
ARG first second third fourth
3. 13 13 13 13
ARG first second third fourth fifth
4. Weber Joe 91
ARG lastname firstname score
5. Baker Amanda Marie 95
PARSE ARG lastname firstname score
6. Callahan Eunice 88 62
PARSE ARG lastname firstname score .

ANSWERS

  1. first = 115, second = -23, third = 66 5.8
  2. first = .2, second = 0, third = 569, fourth = 2E6
  3. first = 13, second = 13, third = 13, fourth = 13, fifth = null
  4. lastname = WEBER, firstname = JOE, score = 91
  5. lastname = Baker, firstname = Amanda, score = Marie 95
  6. lastname = Callahan, firstname = Eunice, score = 88

Passing Arguments

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.

Using the CALL Instruction or a REXX Function Call

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.