Scroll to navigation

ZDSFS(1) General Commands Manual ZDSFS(1)

NAME

zdsfs - File system for z/OS data set access

SYNOPSIS

mounting:

unmounting:

DESCRIPTION

Use the zdsfs command for read access to z/OS data sets stored on one or more DASDs.

The zdsfs file system translates the record-based z/OS data sets to UNIX file system semantics. After mounting the devices, you can use common Linux tools to access the files on the disk. Physical sequential data sets are represented as files. Partitioned data sets are represented as directories, with each member being represented as a file in that directory.

RESTRICTIONS

Only read access is supported.

Data sets on tape devices are not supported.

To maintain data consistency, a DASD must not be modified while it is in use by zdsfs. This can be assured by varying the device offline in z/OS before setting it online in Linux or by using z/OSMF REST services to notify z/OS about access to data sets.

Device access by Linux is not subject to RACF or other z/OS auditing mechanisms unless the z/OSMF REST services are used for a coordinated read access. The safety of the data on the device must be established by therespective Linux mechanisms. By default, zdsfs grants access to the files in the fuse file system only to the user who started the tool. This behavior can be changed by using the options `allow_other', `default_permissions', `umask', `uid', and `gid'.

When using the z/OSMF REST services for coordinated read access, a connection is established for every opened file. The z/OSMF REST services confirm that the z/OS userid that is specified in the .netrc configuration file has the required access rights for the data set. Using this mechanism also an exclusive ENQ is obtained to mark the data set as in use to z/OS. The ENQ prevents z/OS applications from modifying the data set during zdsfs access. If the ENQ cannot be obtained, the access from Linux fails with an error.

Only physical sequential (PS) and partitioned data sets (PDS) are supported. Supported record formats are: V, F, U, B, S, A, and M.

The file system is limited to basic operations: readdir, stat, open, read, and seek. Because the actual size of the data in each track is not always known, zdsfs does not support mmap. Seek operations read the whole data set to the given offset. The performance of seek operations to previous offsets can be improved by buffering seek offsets, see option `-o seekbuffers'.

A further consequence of the unknown exact data size is that zdsfs cannot provide exact file sizes. As a heuristic, the given file sizes are the maximum possible data sizes, based on the number and size of the extents that belong to each data set. When the actual end of the data is reached during read, the usual end of file (EOF) is returned. To ensure that the EOF is passed to the user correctly, the option `-o direct_io' is set by zdsfs implicitly.

Incomplete multi-volume data sets are not detected if only the first volume (device) of the data set is present.

OPTIONS

general options:

<devices> One or more DASD device nodes, where node specifications are
separated by blanks. The device nodes can be specified explicitly with the command or with the -l option and a file.
<mountpoint> The mount point for the specified DASD.
options. For fuse options see "Applicable FUSE options" below, for mount options see mount(8).
Print usage information, then exit.
Print version information, then exit.

zdsfs options:

The specified file <device_list> contains a list of device nodes, separated by white space (space, tab or new line). All device nodes in this file are mounted as if specified directly via the command line.
Keep record descriptor words in the byte stream. By default, data set files contain only the user data.

Record boundaries might be important for applications to correctly interpret the user data. For data sets with variable records, the record descriptor words are required to find the record boundaries. With fixed blocks, record boundaries can be computed from the fixed record sizes.

See `z/OS DFSMS Using Data Sets' for more information about record descriptor words.

Continue processing even if parts of a multi-volume data set are missing. By default, zdsfs ends with an error unless all data sets are complete.

Incomplete data sets can be tolerated, for example, if all data of interest is on another data set that is complete. Incomplete data sets are not represented in the file system. Instead, for each incomplete data set, a warning message is written to the standard error stream.

Size of the track buffer in tracks. The default for <n> is 128.

The data that is read from the DASD must be stored in a buffer, because the minimum size for a read operation in raw access mode is one track, and the user data must be extracted from the track images. Reading more than one track at a time improves the overall performance, but requires larger buffers.

The memory needed by zdsfs for buffering a single track is 64KB for the raw track data and 56KB for the extracted user data. Each time a file is opened a total of (<n> * 120KB) is allocated for the track buffer.

Upper limit in bytes for the seek history buffer size. The default for s is 1048576.

Because the block and record sizes in a data set may vary, the only way to find a data byte at a particular offset (`seek') is to read and interpret the whole data set from the beginning, until the offset is reached.

To improve the performance of `seek' operations in areas that have already been read, zdsfs can buffer offsets in regular intervals. These intervals are multiples of <n> tracks, as specified with the `tracks' option.

For small data sets and large values of <n>, only a few seek offsets need to be buffered. In this case, the amount of memory that is actually allocated can be much smaller than the upper limit <s>.

If <s> is set to 0, no seek history buffer is allocated. In this case `seek' is still supported, but a `seek' operation might result in a read from the beginning of the data set.

Stop processing if the device is used by another operating system instance.

zdsfs configuration file. The default is /etc/zdsfs.conf.

Make zdsfs use z/OSMF REST services for coordinated read access to data sets. The user credentials are taken from .netrc file in the user's home directory or where the NETRC environment variable points to.

Specify up to 3 server URLs to z/OSMF REST services. For multiple specifications, the URLs are tried sequentially, and the first functioning URL is used.

Applicable FUSE options (version 2.8):

This is a selected subset of all FUSE options. Use the zdsfs --help option to print a full list.

Enable debug output (implies -f)
Foreground operation
Allow access by other users
Allow access by root
Allow mounts over non-empty file/dir
Enable permission checking by kernel
Set maximum size of read requests
Cache files in kernel
Enable caching based on modification times
Set file permissions (octal)
Set file owner
Set file group
Set maximum readahead
Perform reads asynchronously (default)
Perform reads synchronously

DATA SET CHARACTERISTICS

Certain data set characteristics might be required for the correct interpretation of the data. The collected metadata of all data sets can be found in a file `metadata.txt' in the top directory of the mounted file system.

This file contains one line per data set, with the syntax that is used by z/OS.

dsn=<data set name>,recfm=<fmt>,lrecl=<size>,dsorg=<org>

dsn: The data set name. For physical sequential data sets, this is the same as the file name in the mount directory. For partitioned data sets (PDS), this is the same as the directory name in the mount directory. For PDS members, the member name is placed after the PDS name, in parentheses.

recfm: The record format.

lrecl: The logical record length.

dsorg: The data set organization. For partitioned data sets the organization is `PO', but for partitioned data set members it is `PS'.

In addition to the `metadata.txt' file, you can use the following extended attributes to read the data set characteristics of a file or directory:

user.recfm: The record format.

user.lrecl: The logical record length.

user.dsorg: The data set organization of a file.

zdsfs configuration file

The default search path is /etc/zdsfs.conf. Use the -c <config_file> option to specify other zdsfs configuration file locations.

The configuration file can contain the following options:

restapi = 0/1

Setting this option to 1 enables the z/OSMF REST services. The z/OSMF REST services require a valid URL specification for a REST server, and a .netrc file with a valid z/OS user ID and password.

restserver = URL

Specifies the URL of the z/OSMF REST server that is used for coordinated read access. For failover, up to 3 different server addresses can be provided.

keepalive = timeout (in seconds)

Specifies the keepalive timer for ENQs. By default the timer is set to 540 seconds to prevent the ENQ from a timeout after 10 minutes in case access to the data set takes longer than this.

EXAMPLES

To mount the z/OS disk with the name dasde enter:


# zdsfs /dev/dasde /mnt

To mount the z/OS disk with space for 4 tracks and keeping the record descriptor words in the byte stream, enter:


# zdsfs -o rdw -o tracks=4 /dev/dasde /mnt

To unmount the z/OS disk mounted on /mnt enter:


# fusermount -u /mnt

To list all extended attributes of file FOOBAR.TEST.TXT assuming the z/OS disk was mounted on /mnt:


# getfattr -d /mnt/FOOBAR.TEST.TXT

To mount the z/OS disk using the z/OSMF REST services for coordinated read access:


# ./zdsfs -o restapi -o restserver=zos1.server.tld/zosmf /dev/dasde /mnt/

SEE ALSO

getfattr(1), fuse(8), z/OS DFSMS Using Data Sets, and Linux on System z: Device Drivers, Features and Commands

2013 s390-tools