PARSE LINEIN is really just an abbreviation for PARSE VALUE LINEIN() WITH, the former being a lot easier to notate.

Note: If you're using REXX Dialog to create a graphical user interface, then you should never use PARSE LINEIN. 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 LINEIN, 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 LINEIN keyword. For example, here we collect one line of text, and assign it to the variable named MyVar:

PARSE LINEIN MyVar

Using PARSE LINEIN by itself (ie, without any token variable names after it) causes the next line to be removed from the default input, and discarded.

When you use the PARSE LINEIN instruction, and 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 PARSE LINEIN 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 LINES() \= 0

      /* Read the line into MyVar */
      PARSE UPPER LINEIN 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