Writing JCL for command execution

Figure 1 illustrates the JCL statements needed to execute the TMP in the background.

Figure 1. JCL needed to process commands in the background

The JCL required to execute the TMP as a batch job includes the following:

A JOB statement, including a jobname and operands that specify the processing options.
An EXEC statement that specifies IKJEFT01 (the TMP) as the program to be executed. The format is:
```
//stepname EXEC PGM=IKJEFT01,DYNAMNBR=nn,PARM='command'
or
//stepname EXEC PGM=IKJEFT01,DYNAMBR=nn,PARMDD=instrdd 
```
Note: The TMP must not run as a V=R. Running the TMP as V=R can cause unpredictable results.

If you are executing commands that dynamically allocate data sets, specify the DYNAMNBR parameter.

You may use the PARM parameter to specify the first command to be executed. The command that is executed is taken from the first line of input indicated by the SYSTSIN DD statement.

If a command or program ABENDs, the TMP will place a return code of 12 (X'C') in register 15 and terminate the job step normally. No further commands or subcommands will be executed after the command that ABENDed.
Note: If you need to pass a command string longer than 100 characters to IKJEFT01, you should use the PARMDD= keyword of the EXEC statement of the JCL, as shown above. The PARM='command' form of passing a parameter is limited to a maximum of 100 characters.

If a command or program returns a non-zero return code to the TMP, the TMP does save this return code and continues processing the next command or subcommand. The return code from the next command replaces the return code. The return code returned by the batch IKJEFT01 job (which is the job condition code) is basically the return code of the last command that has been executed, so the IKJEFT01 return code (such as a job condition code) is the rolling return code from each command invoked with the condition code, which is the last return code of the last command.
There are two alternative entry points available for background execution that provide additional return code and ABEND support. They can be used by substituting PGM=IKJEFT01 on the EXEC statement with one of the following:
- PGM=IKJEFT1A
  - If a command or program being processed by IKJEFT1A ends with a system abend, IKJEFT1A causes the job step to terminate with a X'04C' system completion code. IKJEFT1A also returns the completion code from the command or program in register 15.
  - If a command or program being processed by IKJEFT1A ends with a user abend, IKJEFT1A saves this completion code in register 15 and then terminates.
  - If a command, program or REXX exec being processed by IKJEFT1A returns a non-zero return code to IKJEFT1A, IKJEFT1A saves this return code in register 15 and then terminates. Non-zero return codes to IKJEFT1A from CLISTs will not affect the contents of register 15 and the TMP will continue processing. However, commands invoked by CLISTs can have an affect.
  - For a non-zero return code or an abend from a command or program that was not given control directly by IKJEFT1A or a CLIST running under IKJEFT1A, no return code is saved in register 15 and IKJEFT1A does not terminate.
  - If the command terminates with a non-zero return code, IKJEFT1A saves the return code in register 15, flushes the CLIST, and terminates. This is different than what happens when a command is invoked directly by a REXX exec.
- PGM=IKJEFT1B
  - If a command or program being processed by IKJEFT1B ends with a system or user abend, IKJEFT1B causes the job step to terminate with a X'04C' system completion code. IKJEFT1B also returns the completion code from the command or program in register 15.
  - If a command, program or REXX exec being processed by IKJEFT1B returns a non-zero return code to IKJEFT1B, IKJEFT1B saves this return code in register 15 and then terminates. Non-zero return codes to IKJEFT1B from CLISTs do not affect the contents of register 15 and the TMP continues processing.
  - For a non-zero return code or abend completion code from a program or command that was not given control by IKJEFT1B, no return code is saved in register 15 and IKJEFT1B does not terminate.
- For PGM=IKJEFT1A and PGM=IKJEFT1B, if the job step is terminated with a X'04C' system completion code, the conditional disposition for each data set that is still allocated at step termination will be honored:
  - A DD statement can be freed prior to step termination either by using the DYNALLOC macro (SVC 99) in a program or by executing the TSO/E FREE command. If a DD statement that has a conditional disposition specified has been freed prior to step termination, this DD statement will not have the conditional disposition honored because no data set allocation exists for standard deallocation processing in the initiator to process.
  - The conditional disposition for a data set can only be specified by coding it in the JCL statement for the DD or by using the DYNALLOC macro (SVC 99) and specifying the DALCDISP text unit in the list of text units specified in the SVC 99 request block. The conditional disposition for a data set cannot be specified by using the TSO/E ALLOCATE command.
  If the data set is allocated using the DYNALLOC macro (SVC 99) in a command or program, all of the following requirements must occur in order for the conditional disposition to be honored:
  - The TMP must have been started using alternate entry point IKJEFT1A or IKJEFT1B.
  - The command or program must be invoked directly by the TMP.
  - The command or program must issue the DYNALLOC macro (SVC 99) specifying the DALCDISP text unit in the list of text units specified in the SVC 99 request block.
  - If the IKJEFT1A alternate entry point was used, the command or program must abend with a system abend.
  - If the IKJEFT1B alternate entry point was used, the command or program must abend with either a system or a user abend .
  If the command or program that issued the DYNALLOC macro (SVC 99) does not abend, but a subsequent command or program does abend, the conditional disposition specified in the DYNALLOC macro will not be honored. This is because the TMP treats each command or program as a logical ''step'' and performs all clean up processing (including, but not limited to, data set disposition) at the termination of each command or program invoked directly by the TMP.
  Example 1 - Conditional Disposition honored:
```
//jobcard
//TSO EXEC PGM=IKJEFT1A
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
 command_processor_a   parameters
 command_processor_b   parameters 
```
  - command_processor_a issues a DYNALLOC macro (SVC 99) specifying the DALCDISP text unit and then abends with a system abend at some point after the DYNALLOC is successful
  Because the command or program that issued the DYNALLOC macro (SVC 99) was invoked directly by the TMP and abended before control was returned to the TMP, the conditional disposition specified in the DALCDISP text unit pointed to by the SVC 99 request block will be honored.
  
  Example 2 - Conditional Disposition not honored:
```
//jobcard
//TSO EXEC PGM=IKJEFT1A
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
 command_processor_a   parameters
 command_processor_b   parameters 
```
  - command_processor_a issues a DYNALLOC macro (SVC 99) specifying the DALCDISP text unit and then terminates normally
  - command_processor_b then abends with a system abend
  Because command_processor_a (which issued the DYNALLOC macro (SVC 99)) did not abend, the TMP frees all data sets allocated by command_processor_a. Since this is a normal completion, the conditional disposition of the data sets is not honored.
  
  Example 3 - Conditional Disposition honored:
```
//jobcard
//TSO EXEC PGM=IKJEFT1A
//CONDDISP DD DSN=data.set.name,DISP=(NEW,CATLG,DELETE),
//     UNIT=SYSALLDA,SPACE=(TRK,(1,1))
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
 command_processor_a   parameters
 command_processor_b   parameters
```
  where
  - command_processor_a runs normally
  - command_processor_b then abends with a system abend
  Because the data set was allocated by the JCL DD statement, and was not freed, it is still allocated at the termination of the job step. Since the job step will terminate with a system abend code X'04C' (because command_processor_b abended with a system abend), the conditional disposition for all data sets in the step will be honored.
  
  Example 4 - Conditional Disposition not honored:
```
//jobcard
//TSO EXEC PGM=IKJEFT1A
//CONDDISP DD DSN=data.set.name,DISP=(NEW,CATLG,DELETE),
//     UNIT=SYSALLDA,SPACE=(TRK,(1,1))
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
 command_processor_a   parameters
 FREE FILE(CONDDISP)
 command_processor_b   parameters
```
  - command_processor_a runs normally
  - command_processor_b then abends with a system abend
  Because the data set allocated by the JCL DD statement was freed, the normal disposition (CATLG) for the data set will be honored. The data set will no longer be allocated when the job step ends (with system abend code X'04C' because command_processor_b abended with a system abend). Even though the job step will end with a system abend code, the data set has already been freed and therefore the initiator has no data set allocated for which to perform disposition processing.
  
  For more information about the DYNALLOC macro and the SVC 99 Request Block, see z/OS MVS Programming: Authorized Assembler Services Guide.
  
  For more information about the TSO/E ALLOCATE and FREE commands, see z/OS TSO/E Command Reference.
A SYSTSPRT DD statement that controls output from your job. This DD statement can refer to a system printer or to a sequential or partitioned data set. If the data set is partitioned, you must specify the member name on the DD statement as DSN=pdsname(membername).
Messages issued by programs using the TSO/E I/O service routines are written to the data set indicated by the SYSTSPRT DD statement.
A SYSTSIN DD statement that controls input to your job. Use this statement to indicate which commands and subcommands are to be executed.
You can specify the input data directly following the SYSTSIN DD statement, or you can refer to a sequential or partitioned data set. If the data set is partitioned, you must specify the member name on the DD statement as DSN=pdsname(membername). Each command or subcommand, such as subcommands of TSO/E EDIT, must begin on a separate statement.

It is suggested that the SYSTSIN DD be defined as a fixed block format data set, with an LRECL of 80.

If SYSTSIN is a fixed length data set (FB), the last 8 bytes of the record will be treated as a sequence number and ignored.

If SYSTSIN is a fixed length data set with ASA control characters (FBA), the first byte of the record will be treated as a carriage control character and ignored.

If SYSTSIN is a variable length data set (VB), the first 8 bytes of the record will be treated as a sequence number and ignored.

If SYSTSIN is a variable length data set with ASA control characters (VBA), the first 9 bytes of the record will be treated as a sequence number, followed by a carriage control character and ignored.

Programs that use the TSO/E I/O service routines to obtain input receive their input from the data set indicated by the SYSTSIN DD statement. The records can be up to 72 bytes in length.

Use the SYSPROC DD statement to execute CLISTs implicitly. If a CLIST is a member of a partitioned data set, you can execute the CLIST implicitly by simply specifying the member name. For more information on executing CLISTs, see z/OS TSO/E CLISTs.