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 Dialog to create a graphical user interface, then you should never use PULL. Instead, use RXCREATE() to create a window with an ENTRY control (and perhaps a TEXT control to provide directions), and then use PARSE VAR to parse the value that the user types into the ENTRY, as discussed in Getting input with Rexx Dialog.

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
Actually, before PULL goes to the user for text, it first tries to remove the next data item in the script's Data stack. If there is an item there (ie, you previously PUSH'ed or QUEUE'ed an item onto the Data stack), then PULL parses that item instead. Only if there is no item on the stack will PULL then go to the default input stream. The Data stack is discussed later. To bypass the Data stack, use PARSE LINEIN.

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
 */
SIGNAL ON HALT
DO FOREVER
   /* Is there another line waiting? */
   DO WHILE QUEUED() \= 0 | LINES() \= 0

      /* Read the line into MyVar */
      PULL MyVar

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

      /* 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.
    */
    CALL SLEEP 0

END
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
 */
SIGNAL ON HALT
DO FOREVER
   /* Is there another character waiting? */
   DO WHILE CHARS() \= 0

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

      /* Is it "Q"? */
      IF MyVar = "Q" THEN SIGNAL HALT

      /* 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.
    */
    CALL SLEEP 0

END
HALT:
   RETURN