• Access the command processor parameter list (CPPL).

  When a command processor receives control from the TMP, register 1 contains the address of the CPPL. Use the IKJCPPL DSECT, provided in SYS1.MACLIB, to map the fields in the CPPL. Your command processor can then access the symbolic field names within the IKJCPPL DSECT by using the address contained in register 1 as the starting address for the DSECT. The use of the DSECT is recommended since it protects the command processor from any changes to the CPPL.

• Validate any operands entered with the command.

  Your command processor must verify that the operands the user specified on the command are valid. Use the parse service routine (IKJPARS) to scan and verify the operands, and prompt the user if operands are incorrect or if required operands are missing. See Validating command operands for a description of the functions provided by the parse service routine.

• Communicate with the user at the terminal.

  Your command processor might need to obtain data from the terminal, prompt the user for input, and write messages or data to the terminal. You may also want to display full-screen panels. For information on terminal I/O and full-screen processing, see Communicating with the Terminal User.

• Perform the function of the command according to any operands the user specified.

  The operands that the user specified on the command indicate which functions your command processor should perform. You can use system services and the services provided by TSO/E to perform many functions. For example, your command processor can use the TSO/E service facility

  to invoke other commands, programs, CLISTs, or REXX execs.
• Recognize and pass control to any subcommands.

  If you have chosen to implement subcommands, your command processor must be able to recognize a subcommand name entered by the terminal user and pass control to the requested subcommand processor . For a description of the steps involved, see Passing Control to Subcommand Processors.

• Intercept and process abnormal terminations.

  Your command processor must be able to intercept abnormal terminations and perform the processing needed to keep the system operable. For information on writing error handling routines, see Processing Abnormal Terminations.

• Respond to and process attention interruptions entered from the terminal.

  If your command processor accepts subcommands or operates in full-screen mode, it must be able to respond to an attention interruption entered by the terminal user. Your command processor must provide an attention exit to obtain a line of input from the terminal after an attention interruption occurs. For more information, see Processing Attention Interruptions.

• Set the return code in register 15 and return control to the TMP.
  When returning control to the TMP, your command processor must follow standard linkage conventions and set a return code in register 15. CLISTs that invoke your command processor can check the return code, which is contained in the variable &LASTCC, to determine whether processing was successful. Your command processor can set one of the following return codes in register 15:

  Table 1. Command processor return codes for register 15

  Return Code Dec(Hex)	Meaning
  0(0)	The command processor has executed normally.
  12(C)	An error encountered during execution has caused the command processor to terminate. Note that an error does not occur when the command processor is able to obtain the required information by prompting the user.

If you plan to make your command processor available to other TSO/E users, provide HELP information about the command, subcommands, and all operands. HELP information is displayed at the terminal when the user enters the HELP command and specifies the name of the command or subcommand. See Creating HELP Information.

After you code your command processor, you must assemble the source into object code and place it in an object module. For more information, see Compiling and Assembling Programs.

For methods that you can use to add your new command processor to TSO/E, see Installing a command processor.

See Executing and Testing a command processor.