zPET - IBM Z and z/OS Platform Evaluation and Test - Group home

DSFS introduction

  

Data Set File System (DSFS) is a new type of physical file system that was introduced as a z/OS V2.5 2Q 2022 enhancement.With DSFS, z/OS UNIX applications and users can access data sets by presenting the data sets as a tree-structured file system that is mounted at mount point /dsfs in the z/OS UNIX file system tree. To use the DSFS support, you must install and activate APAR OA62150 (the related PTFs are UJ08232 UJ08233) to install the modules and files that are needed to run DSFS.

 

In this article, the following 4 parts will be introduced for DSFS.

1.     Supported data sets

2.     Utility file system

3.     Components of the DSFS tree

4.     Creating new data sets with DSFS

Now, let’s look at the 4 parts one by one.

1. Supported data sets

Currently, DSFS only supports the following 3 types of data sets:

·      Fixed and variable-length record physical sequential data sets (PS)

·      Partitioned data sets (PDS)

·      Partitioned data set extended (PDSE)

Note: DSFS does not support aliases, VSAM data sets, or migrated data sets.

2. Utility file system

DSFS requires a utility file system to assist it with presentation of z/OS data sets as a file system tree. The utility file system stores UNIX files and directories in a tree that represents data sets accessed by z/OS UNIX users.

 

Note: Each active DSFS member in a sysplex must have its own utility file system.

 

To mount DSFS in the z/OS UNIX tree, mount the utility file system at mount point /dsfs.

 

Even though each system in a shared file system environment will have its own utility file system, z/OS UNIX treats the file system mounted at /dsfs as a single file system. To achieve this, DSFS requires the name of the utility file system data set to have a last qualifier that is the local system name where DSFS is running. For example, in a sysplex with 4 systems named JA0, JB0, JC0 and JD0, the utility file systems could have names such as

OMVSSPN.DSFS.UTILITY.JA0

OMVSSPN.DSFS.UTILITY.JB0

OMVSSPN.DSFS.UTILITY.JC0

OMVSSPN.DSFS.UTILITY.JD0

 

Note: All of the prior qualifiers of the utility file system data set name must match those of the other utility file system data sets used by DSFS on other systems in the sysplex. Additionally, it’s up to you to specify a name of your own for the prior qualifiers of the utility file system data set name.

 

2.1 Defining the utility file system

The utility file system must be defined before it can be mounted. Use the IDCAMS program to define it with ZFS keyword. For example,

DEFINE CLUSTER (NAME(OMVSSPN.DSFS.UTILITY.JA0) -           

  ZFS CYL(2000 , 100) SHAREOPTIONS(3) -                      

  DATACLAS(SMSOE) -                                        

  STORCLAS(SMSOE))

Note: once a utility file system is used by DSFS, it cannot be used by zFS, and vice versa.

 

When you define the utility file system, consider the following factors:

(1) Secondary space allocation: Provide the utility file system with a secondary extent allocation value to allow for dynamic growth of the data set if it becomes full.

(2) Key label: Any access to a z/OS data set that is encrypted requires the utility file system to be encrypted, so define the utility file system with a key label.

(3) Extended addressability: If you want the utility file system to be larger than 4GB, then use SMS DATACLASS for extended addressability.

 

 

 

2.2 Mounting the utility file system

Only one MOUNT command is allowed in the sysplex for DSFS in a shared file system environment. However, each member will use its own utility file system data set specified with the FILESYSTEM parameter on the MOUNT command. The FILESYSTEM parameter must be in uppercase and be the name of the utility file system data set with its system name qualifier removed. Take the previous data set name as an example:

MOUNT FILESYSTEM(‘OMVSSPN.DSFS.UTILITY’) MOUNTPOINT(‘/dsfs’) TYPE(DSFS) MODE(RDWR)

 

When DSFS receives a mount request from z/OS UNIX, it automatically appends the system name to the name provided in the FILESYSTEM parameter of the MOUNT command to determine the name of the local utility file system data set. Then, it attaches and mounts that data set for its use.

 

Important: Do not issue unmount commands for the utility file system. This will cause the utility file system on other members of the sysplex to also be unmounted.

2.3 Displaying usage information for the utility file system

The dsadm fsinfo command displays information about the utility file system. An example of the output is as follows:

128:/u/demi $ dsadm fsinfo                                            

   File System Name:          OMVSSPN.DSFS.UTILITY.JB0                                                                                      

   System:              JB0             Devno:                  11915 

   Size:                3600000K        Free 8K Blocks:         445817

   Free 1K Fragments:   7               Log File Size:          32800K

   Bitmap Size:         512K            Anode Table Size:       24K   

   File System Objects: 34              Version:                1     

   Overflow Pages:      0               Overflow HighWater:     0     

   Space Monitoring:    0,0                                           

   ENOSPC Errors:       0               Disk IO Errors:         0     

   Status:              NE,CO                                         

                                                                       

   File System Creation Time: May 17 15:37:41 2022                    

   Mount Time:                Jun 30 14:52:40 2022                                                                                          

   Last Grow Time:            n/a                                     

                                                                                                                                            

Legend: NE=Not encrypted, CO=Compressed                               

3. Components of the DSFS tree

The following figure shows an example of a DSFS tree:


Figure 1. DSFS directory structure


The DSFS tree has four conceptual levels:

·      ROOT directory

·      PATH directory

·      HLQ directory

·      Data sets

ROOT directory: The root of the DSFS tree is /dsfs, which is read-only. DSFS places txt, bin, rec path directories in this directory at mount time.

 

PATH directory: Determines the processing mode of data sets that are accessed through that path. These directories are automatically created by DSFS if they do not exist in the utility file system. Three processing modes (binary, record, and text) are available with DSFS.

 

Binary (/dsfs/bin): Data sets that are accessed by this path are treated by DSFS as binary data.

Record (/dsfs/rec): Data sets that are accessed by this path are treated by DSFS as z/OS record format files.

Text (/dsfs/txt): Data sets that are accessed by this path are treated by DSFS as text files.

 

High-level qualifier (HLQ) directory: DSFS places a high-level qualifier (HLQ) name in a path directory if the user application changes directory or uses a path name that specifies the HLQ name in the path . Upon first access (for example the cd command), DSFS will populate the HLQ directory in its utility file system with names of supported data sets whose names begin with the HLQ and have at least one other qualifier. The names that appear in the data set level of the DSFS directory tree does not have the HLQ portion. For example, in Figure 1, physical sequential data set scott.file1.out is represented as a file called file1.out in the HLQ directory named scott.

 

Data sets: The data sets belonging to an HLQ that is accessed by a DSFS user has a corresponding file (PS) or directory (PDS or PDSE) created inside the HLQ directory with the HLQ removed. Names appear in lowercase, but users can access the names by using uppercase, lowercase, or mixed-case because DSFS is case-insensitive.

Note: Using lowercase is preferable when accessing the names. If uppercase names are specified, unpredictable results maybe occur. For example, an ls command with a wildcard and uppercase characters will result in failed pattern matching.

# ls my*

my.file

# ls -l my*

-rwxrwxrwx    1 BPXROOT  SYS1           1 Jul 23 00:00 my.file

# ls -l My*

ls: FSUM6785 File or directory "My*" is not found

# ls -l My.file

-rwxrwxrwx    1 BPXROOT  SYS1           1 Jul 23 00:00 My.file

 

4. Creating new data sets with DSFS

DSFS users can create files and directories. A file represents either a PS or a PDS/PDSE member. A directory represents either an HLQ or a PDS/PDSE.

 

For DSFS, creating a new PS, PDS, or PDSE requires the user to supply creation parameters that indicate how to create the data set.

 

4.1 Specifying creation parameters for data sets

With the dsadm createparm command, users can specify data set attributes to use when PS or PDS/PDSE data sets are created. DSFS allows a PS model file creation parameter string for PS data sets and a PDS model directory creation parameter string for PDS/PDSE data sets. Please refer to 4.2 Displaying saved creation parameters for detailed example.

 

The creation parameters are assigned to an HLQ directory and apply to all data sets created with the same HLQ. They are also saved permanently in the utility file system for the directory that represents the HLQ.

 

The user ID of the issuer of the dsadm createparm command must match the HLQ in order to set or replace the creation parameters.

 

An example of specifying the creation parameters for new files and directories is shown as follows.

For new files:

dsadm createparm -path /dsfs/txt/demi -psmodel "cyl dsorg(ps) lrecl(300) recfm(vb) space(5,1) blksize(0)"

For new directories:

dsadm createparm -path /dsfs/txt/demi -pdsmodel "cyl dsorg(po) lrecl(180) recfm(fb) space(5,1) blksize(0) dsntype(library)"

 

4.2 Displaying saved creation parameters

The user can query the creation parameters for an HLQ with the dsadm fileinfo command. Example output from the dsadm fileinfo command is shown as follows.

129:/u/demi $ dsadm fileinfo /dsfs/txt/demi                                                         

   path: /dsfs/txt/demi                                                                            

   fid                    11,1          anode                  160527,3036                          

   length                 8192          format                 BLOCKED                             

   1K blocks              8             dir tree status        VALID                               

   PDS model anode        31,73         PS model anode         32,56                               

   object type            DIR           object linkcount       4                                   

   object genvalue        0x00000000    dir version            1                                   

   dir name count         15            data set name type     na                                  

   recfm                  na            lrecl                  na                                  

   data mode              TEXT          data set status        RETRIEVED                           

   data set name          DEMI                                                                      

   ENQ held               NO                                                                       

   direct blocks          0x0005F68A    0xFFFFFFFF    0xFFFFFFFF    0xFFFFFFFF                     

                          0xFFFFFFFF    0xFFFFFFFF    0xFFFFFFFF    0xFFFFFFFF                     

   indirect blocks        0xFFFFFFFF    0xFFFFFFFF    0xFFFFFFFF                                   

   mtime       Jun 29 03:34:04 2022     atime        Jul  8 02:07:20 2022                          

   ctime       Jun 29 03:34:04 2022     create date  Jun 29 2022                                   

   not encrypted                        not compressed                                             

   PDS model              cyl dsorg(po) lrecl(180) recfm(fb) space(5,1) blksize(0) dsntype(library)

   PS model               cyl dsorg(ps) lrecl(300) recfm(vb) space(5,1) blksize(0)                 

   vnode,vntok          0x00000050,,0x07200B40      0x01325DA0,,0x00000000                         

   opens                oi=0          rd=0          wr=0                                           

   file segments        na         file unscheduled        na                                      

   meta buffers         0          dirty meta buffers      1                                       

 

4.3 Creating new data sets

Users can create, rename, and remove data sets with the standard UNIX commands such as touch, rm, mv

Now let’s look a complete example.

1. Enter the DSFS tree, we can see three directories already exist.

130:/u/demi $ cd /dsfs

131:/dsfs $ ls        

bin  rec  txt          

2.  Go to txt directory, list data sets with HLQ DEMI: ls

Note: As mentioned above, DSFS will populate HLQ DEMI upon its first access (such as cd command)

132:/dsfs $ cd txt

133:/dsfs/txt $ ls

dsfsauto                            

134:/dsfs/txt $ cd demi                     

135:/dsfs/txt/demi $ ls                                                                                                                   

brodcast          c2r1b5e.ckrtcmd   dsfs              ispf.profile      pmr.listclog      spflog1.list      spftemp1.list     svg.nooption         c2r1318.ckrtsprt      c2r1c87.ckrtcmd   file1             jobs.plex         spf1.list         spftemp0.cntl     spftemp2.list 

136:/dsfs/txt/demi $ cd ..

137:/dsfs/txt $ ls

demi      dsfsauto               

3. View the contents of data set svg.nooption: cat

130:/dsfs/txt/demi $ cat svg.nooption

1                    J E S 2  J O B  L O G  --  S Y S T E M  J 8 0    --  N O D E  S 3 9 0 P E T        

0

 02.41.48 J0141219 ---- MONDAY,    15 JUN 2015 ----

 02.41.48 J0141219  IRR010I  USERID DEMI     IS ASSIGNED TO THIS JOB.

 02.41.48 J0141219  ICH70001I DEMI     LAST ACCESS AT 22:13:54 ON SUNDAY, JUNE 14, 2015

 02.41.48 J0141219  $HASP373 XIARZSVG STARTED - INIT 7    - CLASS A        - SYS J80

 02.41.48 J0141219  IEF403I XIARZSVG - STARTED - TIME=02.41.48

 02.41.49 J0141219  IEE252I MEMBER IOEPRM00 FOUND IN SYS1.PARMLIB

 02.41.53 J0141219  -                                         --TIMINGS (MINS.)--            ----PAGING COUNTS---

 02.41.53 J0141219  -JOBNAME  STEPNAME PROCSTEP    RC   EXCP    CPU    SRB  CLOCK   SERV  PG   PAGE   SWAP    VIO SWAPS STEPNO

 02.41.53 J0141219  -XIARZSVG          SALVAGE     00   2449    .01    .00    .07   891K   0      0      0      0     0     1

 02.41.53 J0141219  IEF404I XIARZSVG - ENDED - TIME=02.41.53

 02.41.53 J0141219  -XIARZSVG ENDED.  NAME-Salvage              TOTAL CPU TIME=   .01  TOTAL ELAPSED TIME=   .07

 02.41.53 J0141219  $HASP395 XIARZSVG ENDED - RC=0000

0------ JES2 JOB STATISTICS ------

-  15 JUN 2015 JOB EXECUTION DATE

……. 

4. Specify data set attributes: dsadm createparm

137:/dsfs/txt/demi $ dsadm createparm -path /dsfs/txt/demi -psmodel "cyl dsorg(ps) lrecl(300) recfm(vb) space(5,1) blksize(0)"

138:/dsfs/txt/demi $ dsadm createparm -path /dsfs/txt/demi -pdsmodel "cyl dsorg(po) lrecl(180) recfm(fb) space(5,1) blksize(0) dsntype(library)"

5. Display data set attributes: dsadm fileinfo

129:/u/demi $ dsadm fileinfo /dsfs/txt/demi                                                        

   path: /dsfs/txt/demi                                                                            

   fid                    11,1          anode                  160527,3036                         

   length                 8192          format                 BLOCKED                             

   1K blocks              8             dir tree status        VALID                               

   PDS model anode        31,73         PS model anode         32,56                               

   object type            DIR           object linkcount       4                                   

   object genvalue        0x00000000    dir version            1                                   

   dir name count         15            data set name type     na                                  

   recfm                  na            lrecl                  na                                  

   data mode              TEXT          data set status        RETRIEVED                           

   data set name          DEMI                                                                     

   ENQ held               NO                                                                       

   direct blocks          0x0005F68A    0xFFFFFFFF    0xFFFFFFFF    0xFFFFFFFF                     

                          0xFFFFFFFF    0xFFFFFFFF    0xFFFFFFFF    0xFFFFFFFF                     

   indirect blocks        0xFFFFFFFF    0xFFFFFFFF    0xFFFFFFFF                                   

   mtime       Jun 29 03:34:04 2022     atime        Jul  8 02:07:20 2022                          

   ctime       Jun 29 03:34:04 2022     create date  Jun 29 2022                                   

   not encrypted                        not compressed                                              

   PDS model              cyl dsorg(po) lrecl(180) recfm(fb) space(5,1) blksize(0) dsntype(library)

   PS model               cyl dsorg(ps) lrecl(300) recfm(vb) space(5,1) blksize(0)                 

   vnode,vntok          0x00000050,,0x07200B40      0x01325DA0,,0x00000000                         

   opens                oi=0          rd=0          wr=0                                           

   file segments        na         file unscheduled        na                                       

   meta buffers         0          dirty meta buffers      1                                       

6. Create PS data set: touch file1

149:/dsfs/txt/demi $ touch file1

150:/dsfs/txt/demi $ ls file*  

file1                           

Go to ISPF 3.4 to view this newly created data set: DEMI.FILE1 

DSLIST - Data Sets Matching DEMI.FILE1                              Row 1 of 1

Command ===>                                                  Scroll ===> CSR 

                                                                               

Command - Enter "/" to select action                  Message           Volume

-------------------------------------------------------------------------------

         DEMI.FILE1                                                     SHR011

***************************** End of Data Set list ****************************

7. Create PDS/PDSE data set and members: mkdir

137:/dsfs/txt/demi $ mkdir dsfs        

138:/dsfs/txt/demi $ cd dsfs           

139:/dsfs/txt/demi/dsfs $ touch member1

140:/dsfs/txt/demi/dsfs $ touch member2

141:/dsfs/txt/demi/dsfs $ ls           

member1  member2                       

Go to ISPF 3.4 to view them:

BROWSE            DEMI.DSFS                             Row 0000001 of 0000002

           Name     Prompt       Size   Created          Changed       

_________ MEMBER1                   0  2022/07/08  2022/07/08 02:21:18  

_________ MEMBER2                   0  2022/07/08  2022/07/08 02:21:22 

          **End**                                                            

8. Rename member1 to member0: mv

129:/dsfs/txt/demi/dsfs $ mv member1 member0

130:/dsfs/txt/demi/dsfs $ ls               

member0  member2                            

9. Remove data sets: rm

131:/dsfs/txt/demi/dsfs $ rm member2

132:/dsfs/txt/demi/dsfs $ ls        

member0                             

133:/dsfs/txt/demi/dsfs $ rm member0

134:/dsfs/txt/demi/dsfs $ ls        

135:/dsfs/txt/demi/dsfs $            

OK, that’s all for our DSFS introduction. We welcome any feedback, suggestion, or comments.

 

Author:

Yu Mei, Dai (dyubj@cn.ibm.com)

Alfred Lease (alease@us.ibm.com)

Kieron D Hinds (kdhinds@us.ibm.com)

Comments

Wed April 19, 2023 04:12 AM

@Robert Hunt Hi Robert, thanks for you comment. Please try to cd out of the directory of the PDS

Wed April 19, 2023 01:19 AM

Good blog. Once created and allocated in the USS, a PDS is 'held' by DSFS. How does it get released ?

Fri September 16, 2022 10:08 AM

excellent blog entry, thanks for sharing