Using the parse service routine

When you write a command processor to run under TSO/E, you need a method to determine whether the command operands specified by the user are syntactically correct. The parse service routine (IKJPARS) checks syntax by searching the command buffer for valid operands. If a required operand is missing, or if the user enters an operand incorrectly, parse can prompt the user. The user can enter question marks to receive any second-level messages that are supplied by your command processor that are associated with the operand. Second-level messages provide more explanation of the initial message. Parse can also display HELP information for an operand after the second-level messages have been issued.

Parse recognizes positional and keyword operands. Positional operands occur first, and must be in a specific order. Keyword operands can be entered in any order when they follow all of the positional operands.

Although parse recognizes comments present in the command buffer, it processes by skipping over them. Comments, which are indicated by delimiter /* and */, are not removed from the command buffer.

Before you invoke the parse service routine, your command processor must use the parse macro instructions to create a parameter control list (PCL). The PCL describes the permissible operands. Next, call the parse service routine to compare the information that is supplied by your command processor in the PCL to the operands in the command buffer. Each acceptable operand must have an entry that is built for it in the PCL; an individual entry is called a parameter control entry (PCE).

Parse returns the results of scanning and checking the operands in the command buffer to the command processor in a parameter descriptor list (PDL). The entries in the PDL, called parameter descriptor entries (PDEs), indicate which operands are present in the command buffer. These operands indicate to your command processor the functions the user is requesting.

When your command processor calls the parse service routine, it must pass a parse parameter list (PPL). The PPL contains pointers to control blocks and data areas that are needed by parse. Addresses needed to access the PCL, PDL, and command buffer are included in the parse parameter list.

When the parse server routine finishes processing, it passes a return code in register 15 to your command processor. Your command processor must issue meaningful error messages for all non-zero return codes. To issue meaningful error messages for all non-zero return codes, use the GNRLFAIL routine, in z/OS TSO/E Programming Services.

Figure 1 shows the interaction between the command processor and the parse service routine.