JES spool data sets

Access to JES spool data sets in the z/OS UNIX file system tree is done with the sysout path directory. DSFS automatically creates this directory, which is accessible by all users when ENABLE_SYSOUT=ON is specified.

1. DSFS places a high-level qualifier directory name in the sysout path directory if the user application changes the working directory or uses a path name that specifies the high-level qualifier directory name in that path. The high-level qualifier directory name is the user ID of the requesting user or application. Once the high-level qualifier directory has been created, it cannot be removed. The user ID of the requesting user or application must match the name of a high-level qualifier directory name in order to be allowed access to it. The high-level qualifier directory names in the sysout path are not subject to the HLQ exclude list.
2. DSFS populates high-level directories with the jobs on the JES spool that are owned by the user ID and are not being purged. The name of these job directories takes the form jobname.jesjobid, where jobname is the job name that is specified on the JCL job statement and jesjobid is the job ID that is assigned to the job by JES. The contents of the high-level directory are refreshed each time the directory is accessed.
3. DSFS populates job directories with names that represent job output data sets. These names are also referred to as sysout files. Input and dummy data sets are ignored.
   • The naming convention for the sysout files that represent the system spool data sets is ddname.dskey, where the ddname and dskey values are both assigned by JES.
   • The naming convention for the regular sysout files is stepname.ddname.dskey, where stepname is the name from the JCL execution statement, ddname is the name from JCL data definition statements, and dskey is a data set key assigned to the JES spool data set by the primary JES.
   By using JCL statements, JES can create duplicate spool data sets for use in JES output grouping. These duplicate spool data sets are considered by DSFS as one file and are represented by only one sysout file name. Job directory contents are refreshed each time the job directory is accessed. These sysout file names can be used with standard z/OS UNIX commands and tools to read the data in the spool data sets.

1. User ID BILL submitted a job with the name BILLJOB1 on the JOB statement. The primary JES in this case is JES2.
2. JES2 assigned the job ID JOB00456 to the job.
3. JES2 created three system spool data sets for the job (JESMSGLG, JESJCL and JESYSMSG) and assigned data set keys 2, 3, and 4 to them.

1. DSFS treats sysout files as text files. When a sysout file is accessed, DSFS reads each record from the spool data set. If it is in fixed format, DSFS strips the trailing blanks. For both fixed and variable record formats, DSFS appends a newline character to the end of the record in the POSIX byte stream.
2. Updating sysout files is not supported. You cannot create, rename, or truncate sysout files. You also cannot modify the attributes of sysout files.
3. A sysout file can be removed with the z/OS UNIX rm command. When a sysout file that has duplicates is removed, DSFS attempts to remove all duplicate spool data sets as well. This operation can fail if the spool data set is involved in other JES processing. When the last sysout file of a job is removed, JES may queue the job for purge processing. If that happens, the job directory will be automatically removed in the next refresh of the high-level directory.
4. DSFS does not support modifying the attributes of job directories. DSFS also does not support renaming or creating job directories. DSFS supports the use of the z/OS UNIX rmdir command to remove job directories that have not yet been populated with sysout files. The job will be purged from the JES spool. Otherwise, the rmdir command should not be necessary to purge the job.
5. The only serialization mechanism is a dynamic allocation of the spool data set in SHR mode while the data is being retrieved from the spool data set and is placed in the file cache. This allocation is released when the read is completed. There is no IDFFSPRM option to control how long this dynamic allocation is held.
6. The values for atime, mtime, and ctime for job directories is initially set to the current time of day when the directory itself is created. The atime is updated each time the job directory is accessed. For sysout files, the atime, mtime, and ctime values are initially set to when the spool data set was created. The atime value is updated each time the sysout file is accessed.

The following example shows the SYSOUT-related fields for a dsadm fileinfo command of a SYSOUT high-level qualifier directory:

object type         DIR         object linkcount       141
dir name count      141         data set name type     HLQ DIR
recfm               na          lrecl                  na
data mode           SYSOUT      data set status        RETRIEVED
data set name       SUIMGVY

The following example shows the SYSOUT-related fields for a dsadm fileinfo command of a job directory:

object type         DIR         object linkcount       2
dir name count      5           data set name type     JOB DIR
recfm               na          lrecl                  na
data mode           SYSOUT      data set status        RETRIEVED
data set name       SUIMGVY.SUIMGVY2.JOB01922

The following example shows the SYSOUT-related fields for a dsadm fileinfo command of a sysout file:

object type         FILE        object linkcount       1
dir name count      n/a         data set name type     JOB DIR
recfm               FB          lrecl                  80
data mode           SYSOUT      data set status        SYSOUT FILE
data set name       SUIMGVY.SUIMGVY2.JOB01922.D0000102.?

The attribute fields have the following values:

object type

One of two values:

• DIR for HLQ or job directories.
• FILE for sysout files.

object linkcount

Although data sets do not have link counts, z/OS UNIX objects do. The utility file system keeps the link count of directories equal to the number of subdirectories. For SYSOUT files the link count is always 1. Every z/OS UNIX directory has special entries for . (dot) and .. (dot dot) entries. Job directories have a link count of 2 because the dot and dot dot entries are inserted into the utility file system directory that represents the job.

dir name count

The number of objects in the directory, including the special dot and dot dot entries for directories. For SYSOUT files, the number is the value na.

data set name type

The type of data set that this DSFS object represents (HLQ DIR, JOB DIR, or SYSOUT FILE).

recfm

The record format of the SYSOUT data set. For directories, the value is na.

lrecl

The record length of the SYSOUT data set. For directories, the value is na.

data mode

The processing mode, which is also the path that is chosen in the DSFS file system tree to access the data set. The value is SYSOUT for JES spool objects.

data set status

This field indicates whether DSFS has retrieved the data set contents and converted it to a POSIX byte stream format. If true, then it has the value RETRIEVED. If not, then it has the value UNCACHED. For HLQ and job directories, it has the value RETRIEVED.

data set name

For HLQ directories, the name of the HLQ directory itself (owning user ID).

For job directories, the HLQ directory name combined with the job name and JES job ID. For SYSOUT files, the name of the spool data set.