Defining and allocating QSAM files
You can define a QSAM file or a byte-stream file in the z/OS® UNIX file system by using either a DD statement
or an environment variable. Allocation of these files follows the
general rules for the allocation of COBOL files.
About this task
When you use an environment variable, the name must be in uppercase. Specify the MVS data set in one of these ways:
DSN(data-set-name)DSN(data-set-name(member-name))
data-set-name must be fully qualified
and cannot be a temporary data set (that is, it must not start with &).
Restriction: You cannot create a PDS or PDSE by using an environment variable.
You can optionally specify
the following attributes in any order after DSN:
- A disposition value, one of:
NEW,OLD,SHR, orMOD TRACKSorCYLSPACE(nnn,mmm)VOL(volume-serial)UNIT(type)KEEP,DELETE,CATALOG, orUNCATALOGSTORCLAS(storage-class)MGMTCLAS(management-class)DATACLAS(data-class)
You can use either an environment variable or a DD definition
to define a file in the z/OS UNIX file system.
To do so, define one of the following items with a name that matches
the external name in the ASSIGN clause:
- A
DDallocation that usesPATH='absolute-path-name'andFILEDATA=BINARY - An environment variable with a value
PATH(pathname), where pathname is an absolute path name (starting with/)
For compatibility with releases of COBOL before COBOL for OS/390® & VM Version 2 Release 2, you
can also specify FILEDATA=TEXT when using a DD allocation
for z/OS UNIX files, but this use
is not recommended. To process text files in the z/OS UNIX file system, use LINE SEQUENTIAL organization.
If you do use QSAM to process text files in the z/OS UNIX file system, you cannot use environment
variables to define the files.
When you define a QSAM file, use the parameters as shown below.
| What you want to do | DD parameter to use |
EV keyword to use |
|---|---|---|
| Name the file. | DSNAME (data-set name) |
DSN |
| Select the type and quantity of input-output devices to be allocated for the file. | UNIT |
UNIT for type only |
| Give instructions for the volume in which the file will reside and for volume mounting. | VOLUME (or let the system choose
an output volume) |
VOL |
| Allocate the type and amount of space the file needs. (Only for direct-access storage devices.) | SPACE |
SPACE for the amount of space
(primary and secondary only); TRACKS or CYL for
the type of space |
| Specify the type and some of the contents of the label associated with the file. | LABEL |
n/a |
| Indicate whether you want to catalog, pass, or keep the file after the job step is completed. | DISP |
NEW, OLD, SHR, MOD plus KEEP, DELETE, CATALOG,
or UNCATALOG |
| Complete any data control block information that you want to add. | DCB subparameters |
n/a |
Some of the information about the
QSAM file must always be coded in the FILE-CONTROL paragraph,
the FD entry, and other COBOL clauses. Other information
must be coded in the DD statement or environment
variable for output files. For input files, the system can obtain
information from the file label (for standard label files). If DCB information
is provided in the DD statement for input files,
it overrides information on the data-set label. For example, the amount
of space allocated for a new direct-access device file can be set
in the DD statement by the SPACE parameter.
You
cannot express certain characteristics of QSAM files in the COBOL
language, but you can code them in the DD statement
for the file by using the DCB parameter. Use the
subparameters of the DCB parameter to provide information
that the system needs for completing the data set definition, including
the following items:
- Block size (
BLKSIZE=), ifBLOCK CONTAINS 0 RECORDSorBLOCK0option was specified at compile time (recommended) - Options to be executed if an error occurs in reading or writing a record
TRACK OVERFLOWor standard blocks- Mode of operation for a card reader or punch
DCB attributes coded for a DD DUMMY do
not override those coded in the FD entry of your
COBOL program.
Example: setting and accessing environment variables