ASSIGN clause

The ASSIGN clause associates the name of a file in a program with the actual external name of the data file.

assignment-name-1
Identifies the external data file. It can be specified as a name or as an alphanumeric literal.

assignment-name-1 is not the name of a data item, and assignment-name-1 cannot be contained in a data item. It is just a character string. It cannot contain an underscore character.

Any assignment-name after the first is syntax checked, but has no effect on the execution of the program.

assignment-name-1 has the following formats:

Read syntax diagramSkip visual syntax diagram
Format: assignment-name for QSAM files

>>-+---------+--+-----+--name----------------------------------><
   '-label- -'  '-S- -'         

Read syntax diagramSkip visual syntax diagram
Format: assignment-name for VSAM sequential file

>>-+---------+--AS- --name-------------------------------------><
   '-label- -'               

Read syntax diagramSkip visual syntax diagram
Format: assignment-name for line-sequential, VSAM indexed, or VSAM relative file

>>-+---------+--name-------------------------------------------><
   '-label- -'         

label-
Documents (for the programmer) the device and device class to which a file is assigned. It must end in a hyphen; the specified value is not otherwise checked. It has no effect on the execution of the program. If specified, it must end with a hyphen.
S-
For QSAM files, the S- (organization) field can be omitted.
AS-
For VSAM sequential files, the AS- (organization) field must be specified.

For VSAM indexed and relative files, the organization field must be omitted.

name
A required field that specifies the external name for this file.

It must be either the name specified in the DD statement for this file or the name of an environment variable that contains file allocation information. For details on specifying an environment variable, see Assignment name for environment variable.

name must conform to the following rules of formation:

  • If assignment-name-1 is a user-defined word:
    • The name can contain from one to eight characters.
    • The name can contain the characters A-Z, a-z, and 0-9.
    • The leading character must be alphabetic.
    • The name cannot contain an underscore.
  • If assignment-name-1 is a literal:
    • The name can contain from one to eight characters.
    • The name can contain the characters A-Z, a-z, 0-9, @, #, and $.
    • The leading character must be alphabetic.
    • The name cannot contain an underscore.

For both user-defined words and literals, the compiler folds name to uppercase to form the ddname for the file.

In a sort or merge file, name is treated as a comment.

If the file connector referenced by file-name-1 in the SELECT clause is an external file connector, all file-control entries in the run unit that reference this file connector must have a consistent specification for assignment-name-1 in the ASSIGN clause. For QSAM files and VSAM indexed and relative files, the name specified on the first assignment-name-1 must be identical. For VSAM sequential files, it must be specified as AS-name.

Assignment name for environment variable

The name component of assignment-name-1 is initially treated as a ddname. If no file has been allocated using this ddname, then name is treated as an environment variable.

The environment variable name must be defined using only uppercase because the COBOL compiler automatically folds the external file-name to uppercase.

If this environment variable exists and contains a valid PATH or DSN option (described below), then the file is dynamically allocated using the information supplied by that option.

If the environment variable does not contain a valid PATH or DSN option or if the dynamic allocation fails, then attempting to open the file results in file status 98.

The contents of the environment variable are checked at each OPEN statement. If a file was dynamically allocated by a previous OPEN statement and the contents of the environment variable have changed since the previous OPEN, then the previous allocation is dynamically deallocated prior to dynamically reallocating the file using the options currently set in the environment variable.

When the run unit terminates, the COBOL runtime system automatically deallocates all automatically generated dynamic allocations.

Environment variable contents for a QSAM file

For a QSAM file, the environment variable must contain either a DSN or a PATH option in the format shown below.

Read syntax diagramSkip visual syntax diagram
Format: environment variable for QSAM files, DSN option

>>-DSN(data-set-name-+---------------+-)--+-----+--+--------+--->
                     '-(member-name)-'    +-NEW-+  +-TRACKS-+   
                                          +-OLD-+  '-CYL----'   
                                          +-SHR-+               
                                          '-MOD-'               

>--+-----------------+--+--------------------+------------------>
   '-SPACE(nnn,mmmm)-'  '-VOL(volume-serial)-'   

>--+------------+--+-----------+--+-------------------------+--->
   '-UNIT(type)-'  +-KEEP------+  '-STORCLAS(storage-class)-'   
                   +-DELETE----+                                
                   +-CATALOG---+                                
                   '-UNCATALOG-'                                

>--+----------------------------+--+----------------------+----><
   '-MGMTCLAS(management-class)-'  '-DATACLAS(data-class)-'   

data-set-name must be fully qualified. The data set must not be a temporary data set; that is, it must not start with an ampersand.

After data-set-name or member-name, the data set attributes can follow in any order.

The options that follow DSN (such as NEW or TRACKS) must be separated by a comma or by one or more blanks.

Blanks at the beginning and end of the environment variable contents are ignored. You must not code blanks within the parentheses or between a keyword and the left parenthesis that immediately follows the keyword.

COBOL does not provide a default for data set disposition (NEW, OLD, SHR, or MOD); however, your operating system might provide one. To avoid unexpected results when opening the file, you should always specify NEW, OLD, SHR, or MOD with the DSN option when you use environment variables for dynamic allocation of QSAM files.

For information about specifying the values of the data set attributes, see the description of the DD statement in the z/OS® MVS™ JCL Reference.

Read syntax diagramSkip visual syntax diagram
Format: environment variable for QSAM files, PATH option

>>-PATH(path-name)---------------------------------------------><

path-name must be an absolute path name; that is, it must begin with a slash. For more information about specifying path-name, see the description of the PATH parameter in z/OS MVS JCL Reference.

Blanks at the beginning and end of the environment variable contents are ignored. You must not code blanks within the parentheses or between a keyword and the left parenthesis that immediately follows the keyword.

Environment variable contents for a line-sequential file

For a line-sequential file, the environment variable must contain a PATH option in the following format:

Read syntax diagramSkip visual syntax diagram
Format: environment variable for line-sequential files

>>-PATH(path-name)---------------------------------------------><

path-name must be an absolute path name; that is, it must begin with a slash. For more information about specifying path-name, see the description of the PATH parameter in z/OS MVS JCL Reference.

Blanks at the beginning and end of the environment variable contents are ignored. You must not code blanks within the parentheses or between a keyword and the left parenthesis that immediately follows the keyword.

Environment variable contents for a VSAM file

For an indexed, relative, or sequential VSAM file, the environment variable must contain a DSN option in the following format:

Read syntax diagramSkip visual syntax diagram
Format: environment variable for VSAM files, DSN option

>>-DSN(data-set-name)--+-----+---------------------------------><
                       +-OLD-+   
                       '-SHR-'   

data-set-name specifies the data set name for the base cluster. data-set-name must be fully qualified and must reference an existing predefined and cataloged VSAM data set.

If an indexed file has alternate indexes, then additional environment variables must be defined that contain DSN options (as above) for each of the alternate index paths. The names of these environment variables must follow the same naming convention as used for alternate index ddnames. That is:

  • The environment variable name for each alternate index path is formed by concatenating the base cluster environment variable name with an integer, beginning with 1 for the path associated with the first alternate index and incrementing by 1 for the path associated with each successive alternate index. (For example, if the environment variable name for the base cluster is CUST, then the environment variable names for the alternate indexes would be CUST1, CUST2, ..., .)
  • If the length of the base cluster environment variable name is already eight characters, then the environment variable names for the alternate indexes are formed by truncating the base cluster portion of the environment variable name on the right to reduce the concatenated result to eight characters. (For example, if the environment variable name for the base cluster is DATAFILE, then the environment variable names for the alternate clusters would be DATAFIL1, DATAFIL2, ..., .)

The options that follow DSN (such as SHR) must be separated by a comma or by one or more blanks.

Blanks at the beginning and end of the environment variable contents are ignored. You must not code blanks within the parentheses or between a keyword and the left parenthesis that immediately follows the keyword.

COBOL does not provide a default for data set disposition (OLD or SHR); however, your operating system might provide one. To avoid unexpected results when opening the file, you should always specify OLD or SHR with the DSN option when you use environment variables for dynamic allocation of VSAM files.






Published: 30 November 2018