|
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.
|