A file used within a PL/I program has a PL/I file name. The physical data set external to the program has a name by which it is known to the operating system: a data set name or dsname. In some cases the data set has no name; it is known to the system by the device on which it exists.
The operating system needs a way to recognize which physical data set is referred to by your program, so you must write a data definition or DD statement, external to your program, that associates the PL/I file name with a dsname. For example, if you have the following file declaration in your program:
DCL STOCK FILE STREAM INPUT;
you should create a DD statement with a data definition name (ddname) that matches the name of the PL/I file. The DD statement specifies a physical data set name (dsname) and gives its characteristics:
//GO.STOCK DD DSN=PARTS.INSTOCK, . . .
You'll find some guidance in writing DD statements in this manual, but for more detail refer to the job control language (JCL) manuals for your system.
There is more than one way to associate a data set with a PL/I file. You associate a data set with a PL/I file by ensuring that the ddname of the DD statement that defines the data set is the same as one of the following:
You must choose your PL/I file names so that the corresponding ddnames conform to the following restrictions:
Since external names are limited to 7 characters, an external file name of more than 7 characters is shortened into a concatenation of the first 4 and the last 3 characters of the file name. Such a shortened name is not, however, the name used as the ddname in the associated DD statement.
Consider the following statements:
When statement number 1 is run, the file name MASTER is taken to be the same as the ddname of a DD statement in the current job step. When statement number 2 is run, the name OLDMASTE is taken to be the same as the ddname of a DD statement in the current job step. (The first 8 characters of a file name form the ddname. If OLDMASTER is an external name, it will be shortened by the compiler to OLDMTER for use within the program.) If statement number 3 causes implicit opening of the file DETAIL, the name DETAIL is taken to be the same as the ddname of a DD statement in the current job step.
In each of the above cases, a corresponding DD statement must appear in the job stream; otherwise, the UNDEFINEDFILE condition is raised. The three DD statements could start as follows:
If the file reference in the statement which explicitly or implicitly opens the file is not a file constant, the DD statement name must be the same as the value of the file reference. The following example illustrates how a DD statement should be associated with the value of a file variable:
DCL PRICES FILE VARIABLE,
RPRICE FILE;
PRICES = RPRICE;
OPEN FILE(PRICES);
The DD statement should associate the data set with the file constant RPRICE, which is the value of the file variable PRICES, thus:
//RPRICE DD DSNAME=...
Use of a file variable also allows you to manipulate a number of files at various times by a single statement. For example:
DECLARE F FILE VARIABLE,
A FILE,
B FILE,
C FILE;
.
.
.
DO F=A,B,C;
READ FILE (F) ...;
.
.
.
END;
The READ statement reads the three files A, B, and C, each of which can be associated with a different data set. The files A, B, and C remain open after the READ statement is executed in each instance.
The following OPEN statement illustrates use of the TITLE option:
OPEN FILE(DETAIL) TITLE('DETAIL1');For this statement to be executed successfully, you must have a DD statement in the current job step with DETAIL1 as its ddname. It could start as follows:
//DETAIL1 DD DSNAME=DETAILA,...
Thus, you associate the data set DETAILA with the file DETAIL through the ddname DETAIL1.