Rational Developer for System z
Enterprise PL/I for z/OS, Version 3.8, Programming Guide

Specifying characteristics using DD_DDNAME environment variables

You use the export command to establish an environment variable that identifies the data set to be associated with a PL/I file, and, optionally, provide additional characteristics of that data set. This information provided by the environment variable is called data definition (or DD) information.

The syntax of the DD_DDNAME environment variable is:

Read syntax diagramSkip visual syntax diagram                      .---------------.
                      V               |
>>-DD_DDNAME=filespec---+-----------+-+------------------------><
                        '-,--option-'
 

Blanks are acceptable within the syntax. In addition, the syntax of the statement is not checked at the time the command is entered. It is verified when the data set is opened. If the syntax is wrong, UNDEFINEDFILE is raised with the oncode 96.

DD_DDNAME
Specifies the name of the environment variable. The DDNAME must be in upper case and can be either the name of a file constant or an alternate DDNAME that you specify in the TITLE option of your OPEN statement. The TITLE option is described in Using the TITLE option of the OPEN statement.

If you use an alternate DDNAME, and it is longer than 31 characters, only the first 31 characters are used in forming the environment variable name.

filespec
Specifies a file or the name of a device to be associated with the PL/I file.
option
The options you can specify as DD information.

The options that you can specify as DD information are described in the pages that follow, beginning with APPEND and ending with TYPE.

APPEND

The APPEND option specifies whether an existing data set is to be extended or recreated.

Read syntax diagramSkip visual syntax diagram             .-Y-.
>>-APPEND--(-+-N-+-)-------------------------------------------><
 

Y
Specifies that new records are to be added to the end of a sequential data set, or inserted in a relative or indexed data set.
N
Specifies that, if the file exists, it is to be recreated.

The APPEND option applies only to OUTPUT files. APPEND is ignored if:

BUFSIZE

The BUFSIZE option specifies the number of bytes for a buffer.

Read syntax diagramSkip visual syntax diagram>>-BUFSIZE--(n)------------------------------------------------><
 

RECORD output is buffered by default and has a default value for BUFSIZE of 64k. STREAM output is buffered, but not by default, and has a default value for BUFSIZE of zero.

If the value of zero is given to BUFSIZE, the number of bytes for buffering is equal to the value specified in the RECSIZE or LRECL option.

The BUFSIZE option is valid only for a consecutive binary file. If the file is used for terminal input, you should assign the value of zero to BUFSIZE for increased efficiency.

CHARSET for record I/O

This version of the CHARSET option applies only to consecutive files using record I/O. It gives the user the capability of using ASCII data files as input files, and specifying the character set of output files.

Read syntax diagramSkip visual syntax diagram              .-ASIS---.
>>-CHARSET--(-+-EBCDIC-+-)-------------------------------------><
              '-ASCII--'
 

Choose a suboption of CHARSET based on what form the file has (input) or what form you want the file have (output).

CHARSET for stream I/O

This version of the CHARSET option applies for stream input and output files. It gives the user the capability of using ASCII data files as input files, and specifying the character set of output files. If you attempt to specify ASIS when using stream I/O, no error is issued and character sets are treated as EBCDIC.

Read syntax diagramSkip visual syntax diagram              .-EBCDIC-.
>>-CHARSET--(-+-ASCII--+-)-------------------------------------><
 

Choose a suboption of CHARSET based on what form the file has (input) or what form you want the file to have (output).

DELAY

The DELAY option specifies the number of milliseconds to delay before retrying an operation that fails when a file or record lock cannot be obtained by the system.

Read syntax diagramSkip visual syntax diagram            .-0-.
>>-DELAY--(-+-n-+-)--------------------------------------------><
 

This option is applicable only to VSAM files.

DELIMIT

The DELIMIT option specifies whether the input file contains field delimiters or not. A field delimiter is a blank or a user-defined character that separates the fields in a record. This is applicable for sort input files only.

Read syntax diagramSkip visual syntax diagram              .-N-.
>>-DELIMIT--(-+-Y-+-)------------------------------------------><
 

The sort utility distinguishes text files from binary files with the presence of field delimiters. Input files that contain field delimiters are processed as text files; otherwise, they are considered to be binary files. The library needs this information in order to pass the correct parameters to the sort utility.

LRECL

The LRECL option is the same as the RECSIZE option.

Read syntax diagramSkip visual syntax diagram>>-LRECL--(n)--------------------------------------------------><
 

If LRECL is not specified and not implied by a LINESIZE value (except for TYPE(FIXED) files, the default is 1024.

LRMSKIP

The LRMSKIP option allows output to commence on the nth (n refers to the value specified with the SKIP option of the PUT or GET statement) line of the first page for the first SKIP format item to be executed after a file is opened.

Read syntax diagramSkip visual syntax diagram              .-N-.
>>-LRMSKIP--(-+-Y-+-)------------------------------------------><
 

If n is zero or 1, output commences on the first line of the first page.

PROMPT

The PROMPT option specifies whether or not colons should be visible as prompts for stream input from the terminal.

Read syntax diagramSkip visual syntax diagram             .-N-.
>>-PROMPT--(-+-Y-+-)-------------------------------------------><
 

PUTPAGE

The PUTPAGE option specifies whether or not the form feed character should be followed by a carriage return character. This option applies only to printer-destined files. Printer-destined files are stream output files declared with the PRINT attribute, or record output files declared with the CTLASA environment option.

Read syntax diagramSkip visual syntax diagram              .-NOCR-.
>>-PUTPAGE--(-+-CR---+-)---------------------------------------><
 

NOCR
Indicates that the form feed character ('0C'x) is not followed by a carriage return character ('0D'x).
CR
Indicates that the carriage return character is appended to the form feed character. This option should be specified if output is sent to non-IBM printers.

RECCOUNT

The RECCOUNT option specifies the maximum number of records that can be loaded into a relative or regional data set that is created during the PL/I file opening process.

Read syntax diagramSkip visual syntax diagram>>-RECCOUNT--(n)-----------------------------------------------><
 

The RECCOUNT option is ignored if PL/I does not create, or recreate, the data set.

The default for the RECCOUNT option is 50.

Note: Under z/OS, it is recommended to omit the TITLE option with both the /filespec parameter and RECCOUNT parameter for improved functionality and performance of REGIONAL(1) data sets. In such a case, the number of records that will be loaded into the file depends on the space allocated to the first extent of the data set. See Defining and using regional data sets for additional information.

RECSIZE

The RECSIZE option specifies the length, n, of records in the data set.

Read syntax diagramSkip visual syntax diagram              .-512-.
>>-RECSIZE--(-+-n---+-)----------------------------------------><
 

For regional and fixed-length data sets, RECSIZE specifies the length of each record in the data set; for all other data set types, RECSIZE specifies the maximum length records may have.

SAMELINE

The SAMELINE option specifies whether the system prompt occurs on the same line as the statement that prompts for input.

Read syntax diagramSkip visual syntax diagram               .-N-.
>>-SAMELINE--(-+-Y-+-)-----------------------------------------><
 

The following examples show the results of certain combinations of the PROMPT and SAMELINE options:

Example 1
Given the statement PUT SKIP LIST('ENTER:');, output is as follows:
prompt(y), sameline(y)prompt(n), sameline(y)prompt(y), sameline(n) prompt(n), sameline(n) ENTER: (cursor)ENTER: (cursor)ENTER:(cursor)ENTER:(cursor)
Example 2
Given the statement PUT SKIP LIST('ENTER');, output is as follows:
prompt(y), sameline(y)prompt(n), sameline(y)prompt(y), sameline(n)  prompt(n), sameline(n) ENTER: (cursor)ENTER (cursor)ENTER:(cursor)ENTER(cursor)

SKIP0

The SKIP0 option specifies where the line cursor moves when SKIP(0) statement is coded in the source program. SKIP0 applies to terminal files that are not linked as PM applications.

Read syntax diagramSkip visual syntax diagram            .-N-.
>>-SKIP0--(-+-Y-+-)--------------------------------------------><
 

SKIP0(N)
Specifies that the cursor is to be moved to the beginning of the next line.
SKIP0(Y)
Specifies that the cursor to be moved to the beginning of the current line.

The following example shows how you could make the output to the terminal skip zero lines so that the cursor moves to the beginning of the current output line:

  export DD_SYSPRINT='stdout:,SKIP0(Y)'

TYPE

The TYPE option specifies the format of records in a native file.

Read syntax diagramSkip visual syntax diagram           .-LF------.
>>-TYPE--(-+-CRLF----+-)---------------------------------------><
           +-TEXT----+
           +-FIXED---+
           +-CRLFEOF-+
           '-U-------'
 

CRLF
Specifies that records are delimited by the CR - LF character combination. ('CR' and 'LF' represent the ASCII values of carriage return and line feed, '0D'x and '0A'x, respectively. For an output file, PL/I places the characters at the end of each record; for an input file, PL/I discards the characters. For both input and output, the characters are not counted in consideration for RECSIZE.

The data set must not contain any record that is longer than the value determined for the record length of the data set.

LF
Specifies that records are delimited by the LF character combination. ('LF' represents the ASCII values of feed or '0A'x.) For an output file, PL/I places the characters at the end of each record; for an input file, PL/I discards the characters. For both input and output, the characters are not counted in consideration for RECSIZE.

The data set must not contain any record that is longer than the value determined for the record length of the data set.

TEXT
Equivalent to LF.
FIXED
Specifies that each record in the data set has the same length. The length determined for records in the data set is used to recognize record boundaries.

All characters in a TYPE(FIXED) file are considered as data, including control characters if they exist. Make sure the record length you specify reflects the presence of these characters or make sure the record length you specify accounts for all characters in the record.

CRLFEOF
Except for output files, this suboption specifies the same information as CRLF. When one of these files is closed for output, an end-of-file marker is appended to the last record.
U
Indicates that records are unformatted. These unformatted files cannot be used by any record or stream I/O statements except OPEN and CLOSE. You can read from a TYPE(U) file only by using the FILEREAD built-in function. You can write to a TYPE(U) file only by using the FILEWRITE built-in function.

The TYPE option applies only to CONSECUTIVE files, except that it is ignored for printer-destined files with ASA(N) applied.

If your program attempts to access an existing data set with TYPE(FIXED) in effect and the length of the data set is not a multiple of the logical record length you specify, PL/I raises the UNDEFINEDFILE condition.

When using nonprint files with the TYPE(FIXED) attribute, SKIP is replaced by trailing blanks to the end of the line. If TYPE(LF) is being used, SKIP is replaced by LF with no trailing blanks.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)