Rational Developer for System z
COBOL for Windows, Version 7.5, Language Reference


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
Can be specified either as a user-defined word or as an alphanumeric literal.
User-defined word
assignment-name-1 must follow the rules for a COBOL word. The name component of the assignment name can be up to 30 bytes in length. A user-defined word is treated as one of the following:
  • Environment variable name: At program initialization, the name is used as an environment variable. If the environment variable value is set, that value is treated as the system file name optionally preceded by the file-system ID. See Assignment name for data-names and environment variables for details.
  • System file ID of the platform: If the environment variable indicated by the name is not set, the user-defined word is treated as the system file name, optionally preceded by the file-system ID and a comment character string. See Assignment name for non-environment variables and literals for details.
Literal
assignment-name-1 is treated as the actual file ID for the platform. assignment-name-1 must follow the rules for a COBOL literal and have a length of one to 160 characters. See Assignment name for non-environment variables and literals for details.

All characters specified within the literal delimiters are used without any mapping.

 
USING data-name-9
Must be defined in the working-storage section as a data item of category alphanumeric, and must not be subordinate to the file description for file-name-1. The content is evaluated when opened to identify the assignment name. See Assignment name for data-names and environment variables for details.

Assignment name for non-environment variables and literals

If a literal or a word that is not a data-name is specified for the name, the assignment name is processed as follows:

Format: assignment name
Read syntax diagramSkip visual syntax diagram>>-+-----------+--+------------------+-------------------------->
   '-comment- -'  '-file-system-ID- -'  
 
>--+-system-file-name--+---------------+-+---------------------><
   |                   '-| alt-index |-' |  
   '-environment-variable-name-----------'  
 
alt-index:
 
                          .----------------------------------.    
                          V                                  |    
|--(alt-index-file-name-1---+------------------------------+-+-)--|
                            '-,--+-----------------------+-'      
                                 '-alt-index-file-name-2-'        
 
comment
All characters to the left of the system-file ID are treated as comments. Comments can be hyphenated, for example, my-comment or this-is-my-comment.
file-system-ID
The first three characters of file-system-ID are used to determine the file-system identifier. If the character string for file-system-ID is less than three characters, then the entire character string (along with any character strings to the left of it) is treated as a comment. If you include comments (hyphenated or not), you must include the separating hyphen between the comment and file-system-ID.

For example:

my-comment-stl-myfile

In this example, my-comment is the comment, stl is the file-system-ID, and myfile is the system-file-name or environment-variable-name.

my-comment-am-myfile

In this example, my-comment-am is the comment, and myfile is the system-file-name or environment-variable-name.

system-file-name or environment-variable-name
If the assignment name is not specified in the literal form and the environment variable that matches the character string is found at run time, the environment variable value is used to identify the file system and the system file name. Otherwise, the character string is used as the system file name.

Specifying alternate indexes: The compiler normally assigns default alternate index file names; however, you must override the default assignment when the file already exists and has alternate index files with names that differ from the default alternate index file names that are assigned by the compiler. For example, a file created through a different language, such as PL/I.

Alternate index names, if specified, must be specified in the same order as the alternate record keys are specified in the source program. You can omit alternate index names, but any other alternate index names must correspond to the position in the file definition. The following example shows how to specify the first and third alternate index names:

base-file-name(first-index-file-name,,third-index-file-name)

In the above example, the compiler will assign a default file name for the second alternate index file.

Alternate index file names are ignored for file systems that do not require separate alternate index files, such as the STL file system.

Assignment name for data-names and environment variables

If the environment variable or data-name is specified for the assignment name, the data-name value or the environment variable value is processed as follows:

Format: Environment variable and data name value
Read syntax diagramSkip visual syntax diagram>>-+------------------+--system-file-name----------------------->
   '-file-system-ID- -'                    
 
>--+---------------------------------------------------------------+-><
   |                        .----------------------------------.   |  
   |                        V                                  |   |  
   '-(alt-index-file-name-1---+------------------------------+-+-)-'  
                              '-,--+-----------------------+-'        
                                   '-alt-index-file-name-2-'          
 
file-system-ID
If file-system-ID is specified explicitly using the environment variable value or the data-name value, that specification for the file system overrides any file system specification made by the assignment name.

The environment variable value for a file is obtained when the program that contains the file is first run (or called) in its initial state. This value is kept for the file for subsequent calls to the program in the last-used state.

The value of the file ID specified with a data-name is obtained when the file is opened. On each subsequent OPEN for the file, the value is reobtained.

File declarations for an external file must have the same file-system identifier. If they do not, the error is caught during run time, and the application is terminated with an error message.

system-file-name
If there is a hyphen in the environment variable or the data name value, the first three characters to the left of the leftmost hyphen are treated as the file-system identifier. The character string to right of the leftmost hyphen is then used as the system file name (possibly including drive and path names).

If there is no hyphen, or the character string to the left of the leftmost hyphen is less than three characters long, the entire character string is used as the system file name (possibly including drive and path names).

For information about specifying alternate indexes, see “Specifying alternate indexes” under Assignment name for non-environment variables and literals.


Terms of use | Feedback

Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)