The PULL keyword parses a line of text from the default input stream, which is usually the user entering text. A command prompt window will be open and the user will type his text at the keyboard. As he types characters, they will automatically be displayed in the window.

Note: If you're using REXX GUI to create a graphical user interface, then you should never use PULL. Instead, consult Getting input with Rexx Gui.

When you use PULL, your REXX script is halted until the user types some characters and then presses the ENTER key. Then, these characters are returned to your script as one line of text, and parsed using whatever variables, search strings, etc, you have listed after the PULL keyword. For example, here we collect one line of text, and assign it to the variable named MyVar:

PULL MyVar

PULL is actually an abbreviation for PARSE UPPER PULL, so for example, the following 2 lines are identical:

PARSE UPPER PULL token.1
PULL token.1
You'll note that PULL always upper-cases everything. If you do not desire this, then use PARSE PULL instead (ie, remove the UPPER keyword), as so:
PARSE PULL token.1

When you use the PULL or PARSE PULL instructions, and there are no lines in the Data stack, nor the user has yet typed any characters in the command prompt window, then your REXX script is halted until such time as the user types some characters and presses the ENTER key.

For some reason, it may be important that your script not be halted. For example, perhaps there is something else that you would like to be doing in a loop while waiting for the user to type some characters. In this case, the CHARS() or LINES() built-in functions can be used to check if the user has already typed some appropriate characters, thus eliminating the need to wait. If you intend to use PULL or LINEIN(), use LINES() to check if a line has already been typed. If you intend to use CHARIN(), then use CHARS() to check if any characters have already been typed.

For example, here is how to loop around doing something while also checking if the user has typed any line:

/* Loop continuously until user presses CTRL-C,
 * or types QUIT and presses ENTER.
 */

OPTIONS "C_CALL"

DO FOREVER
   /* Is there another line waiting? */
   DO WHILE LINES() \= 0

      /* Read the line into MyVar */
      PULL MyVar

      /* Is it "QUIT"? */
      IF MyVar = "QUIT" THEN RAISE HALT 2

      /* There's a line, but it's not "QUIT".
       * Here you may want to do something
       * else with it.
       */
   END

   /* There are no more lines currently
    * waiting to be read. Here you may do
    * something else while waiting for user
    * input. But, make sure that you don't
    * take too long, or your script will seem
    * unresponsive to the user.
    */

   /* Upon multi-tasking operating systems,
    * it is not good to "busy-wait". So, force
    * a task switch by calling Sleep() if your
    * interpreter supports it.
    */
    SLEEP(0)

END

CATCH HALT
   RETURN
Here is a similiar example, except we use CHARIN() and CHARS() to simply check for the user typing a "Q" to quit. (ie, He does not need to press the ENTER key).
/* Loop continuously until user presses CTRL-C,
 * or types Q to quit.
 */

OPTIONS "C_CALL"

DO FOREVER
   /* Is there another character waiting? */
   DO WHILE CHARS() \= 0

      /* Read the character into MyVar */
      MyVar = CHARIN(,,1)

      /* Is it "Q"? */
      IF UPPER(MyVar) = "Q" THEN RAISE HALT 2

      /* There's a character, but it's not "Q".
       * Here you may want to do something
       * else with it.
       */
   END

   /* There are no more characters currently
    * waiting to be read. Here you may do
    * something else while waiting for user
    * input. But, make sure that you don't
    * take too long, or your script will seem
    * unresponsive to the user.
    */

   /* Upon multi-tasking operating systems,
    * it is not good to "busy-wait". So, force
    * a task switch by calling Sleep() if your
    * interpreter supports it.
    */
    SLEEP(0)

END

CATCH HALT
   RETURN