5.9.3 Allocating program output data files and performing postprocessing

JP1/Advanced Shell automatically creates execution results output files for the purpose of providing centralized management of the output results from user programs as well as of the system execution logs. These files are called program output data files.

The #-adsh_spoolfile command automatically generates the file paths of the program output data files that acquire the execution results output by user programs, and assigns the required shell variables and environment variables.

Organization of this subsection

(1) Allocating program output data files
(2) Names of program output data files
(3) Example of usage of program output data files

(1) Allocating program output data files

Automatically create the file path of a program output data file and then allocate it to the shell variable or environment variable that has the same name as the specified file environment variable definition name. These variables are reset to their initial values when the job step or job terminates. No file entity is created.

To Page Top

(2) Names of program output data files

The name of a program output data file consists of such elements as the job name or job step name, a number, and a file environment variable definition name specified in the #-adsh_spoolfile command. Such a name is unique for each file definition in the job definition script.

An allocated program output data file is stored in the directory for the corresponding job in the spool root directory specified in the SPOOL_DIR environment setting parameter. If no spool root directory is specified in the environment setting parameter, the default value of the SPOOL_DIR parameter is used as the spool root directory. For details about the SPOOL_DIR parameter, see 7. Parameters Specified in the Environment Files.

The format of program output data file names is shown below. In Windows, the file name is appended with the extension .sysout.

Name of a program output data file that is allocated outside the job step

0000_job-name_sequence-number-of-file-environment-variable-definition-name_file-environment-variable-definition-name

Name of a program output data file that is allocated inside the job step

step-number_step-name_sequence-number-of-file-environment-variable-definition-name_file-environment-variable-definition-name

If the child job was executed with MERGE (merging a child job's spool job into the root job's spool job) specified in the SPOOLJOB_CHILDJOB parameter in the root job's environment file, the following file name is used:

When allocated outside the job step

Cnumber-giving-the-order-in-which-a-child-job-starts_0000_job-name_sequence-number-of-file-environment-variable-definition-name_file-environment-variable-definition-name

When allocated within the job step

Cnumber-giving-the-order-in-which-a-child-job-starts_step-number_step-name_sequence-number-of-file-environment-variable-definition-name_file-environment-variable-definition-name

The variable parts of the program output data file name are replaced with the following information:

step-number

Four-digit decimal number assigned sequentially to each job step. The step number of the first job step is 1.

Examples: 0001, 0034, 4095

job-name

Job name specified with the #-adsh_job command. The length of a job name is variable with a maximum length of eight bytes. If a specified character string exceeds eight bytes, the first eight bytes are used as the job name.

step-name

Job step name specified with the #-adsh_step_start command. The length of a job step name is variable with a maximum length of eight bytes. If a specified character string exceeds eight bytes, the first eight bytes are used as the job step name.

sequence-number-of-file-environment-variable-definition-name

Sequential number of a program output data file that was allocated outside the job step or that was allocated inside each job step. The sequence number of a file environment variable definition name is a three-digit decimal number. The value range is from 1 through 255 outside the job step and inside each job step.

Examples: 001, 034, 255

file-environment-variable-definition-name

File environment variable definition name specified with the #-adsh_spoolfile command.

number-giving-the-order-in-which-a-child-job-starts

Sequential number indicating the order in which a child job started within the root job. It consists of seven decimal digits in the range of 0000001 to 9999999.

To Page Top

(3) Example of usage of program output data files

This subsection explains the results of program output data file creation when the following job definition script is executed.

#-adsh_job JOBSAMPLE001
 
#-adsh_spoolfile SYS001                        -->1.
#-adsh_spoolfile SYS002                        -->2.
echo "----- job01 --------" 1>&2
echo "SYS001" > $SYS001
echo "SYS002" > $SYS002
 
#-adsh_step_start STEP01
    #-adsh_spoolfile SYS001                    -->3.
    #-adsh_spoolfile SYS002                    -->4.
    echo "----- Step001 --------" 1>&2
    echo "SYS001" > $SYS001
    echo "SYS002" > $SYS002
#-adsh_step_end
 
#-adsh_spoolfile SYS001                         -->5.
#-adsh_spoolfile SYS002                         -->6.
echo "----- job02 --------" 1>&2
echo "SYS001" > $SYS001
echo "SYS002" > $SYS002
 
#-adsh_step_start STEP02
    #-adsh_spoolfile SYS001                      -->7.
    #-adsh_spoolfile SYS002                      -->8.
    echo "----- Step002 --------" 1>&2
    echo "SYS001" > $SYS001
    echo "SYS002" > $SYS002
#-adsh_step_end
 
#-adsh_spoolfile SYS001                          -->9.
#-adsh_spoolfile SYS002                          -->10.
echo "----- job03 --------" 1>&2
echo "SYS001" > $SYS001
echo "SYS002" > $SYS002

When this job definition script is executed, the program output data files with the file names shown below are created. The numbers at the right end of the job definition script lines correspond to the numbers assigned to the program output data files that are created.

In Windows

1.     0000_JOBSAMPL_001_SYS001.sysout
2.     0000_JOBSAMPL_002_SYS002.sysout
3.     0001_STEP01_001_SYS001.sysout
4.     0001_STEP01_002_SYS002.sysout
5.     0000_JOBSAMPL_003_SYS001.sysout
6.     0000_JOBSAMPL_004_SYS002.sysout
7.     0002_STEP02_001_SYS001.sysout
8.     0002_STEP02_002_SYS002.sysout
9.     0000_JOBSAMPL_005_SYS001.sysout
10.    0000_JOBSAMPL_006_SYS002.sysout

In UNIX

1.     0000_JOBSAMPL_001_SYS001
2.     0000_JOBSAMPL_002_SYS002
3.     0001_STEP01_001_SYS001
4.     0001_STEP01_002_SYS002
5.     0000_JOBSAMPL_003_SYS001
6.     0000_JOBSAMPL_004_SYS002
7.     0002_STEP02_001_SYS001
8.     0002_STEP02_002_SYS002
9.     0000_JOBSAMPL_005_SYS001
10.    0000_JOBSAMPL_006_SYS002

To Page Top