Rational Developer for System z
PL/I for Windows, Version 8.0, Programming Guide

Specifying characteristics using DD:ddname environment variables

You use the SET 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>>-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 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.

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

AMTHD

The AMTHD option specifies the access method that is to be used to access the data set.

Read syntax diagramSkip visual syntax diagram            .-FSYS----.
>>-AMTHD--(-+-DDM-----+-)--------------------------------------><
            +-ISAM----+
            +-BTRIEVE-+
            '-REMOTE--'
 
FSYS
Specifies that PL/I is to use its native access methods to access a native file. This is the default.
ISAM
Specifies that the ISAM access method is to be used to access an ISAM file.
BTRIEVE (Windows)
Specifies that the BTRIEVE access method is to be used to access a BTRIEVE file.
REMOTE (Windows)
Specifies that the file resides on a remote DDM target system (such as MVS).

For Windows, the name of the file needs to be qualified by the LU alias or the fully-qualified SNA network name

FSYS is used by default if you do not specify the AMTHD option and if you do not apply one of the following ENVIRONMENT options:

If you specify any of the above options, AMTHD(ISAM)is the default on Windows while AMTHD(DDM) is the default on AIX.

APPEND

The APPEND option specifies whether an existing data set is to be extended or re-created.

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. This is the default.
N
Specifies that, if the file exists, it is to be re-created.

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

ASA

The ASA option applies to printer-destined files. This option specifies when the ANS control character in each record is to be interpreted.

Read syntax diagramSkip visual syntax diagram          .-N-.
>>-ASA--(-+-Y-+-)----------------------------------------------><
 
N
Specifies that the ANS print control characters are to be translated to IBM Proprinter control characters as records are written to the data set. This is the default.
Y
Specifies that the ANS print control characters are not to be translated; instead they are to be left as is for subsequent translation by a process you determine.

If the file is not a printer-destined file, the option is ignored. Printer-destined files are described in Printer-destined files.

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 EBCDIC 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(ASIS) is the default.

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 EBCDIC 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 ASCII.

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

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

CHARSET(ASCII) is the default.

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>>-DELAY--(n)--------------------------------------------------><
 

The default value for DELAY is 0. .

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-+-)-------------------------------------------><
 

PROMPT(N) is the default.

PUTPAGE

The PUTPAGE option specifies whether or not the form feed character should be followed by a carriage return character. This option only applies 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). This is the default.
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 re-create, the data set. If the RECCOUNT option applies and is omitted, the default is 50 for regional and relative files.

RECSIZE

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

Read syntax diagramSkip visual syntax diagram>>-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.

The default for n is 512.

RETRY

The RETRY option specifies the number of times an operation should be retried when a file or record lock cannot be obtained by the system.

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

The default value for RETRY is 10. This option is applicable only to DDM files.

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)

SHARE

The SHARE option specifies the level of file sharing to be allowed.

Read syntax diagramSkip visual syntax diagram            .-NONE-.
>>-SHARE--(-+-READ-+-)-----------------------------------------><
            '-ALL--'
 
NONE
Specifies that the file is not to be shared with other processes. This is the default.
READ
Specifies that other processes can read the file.
ALL
Specifies that other processes can read or write the file. Data integrity is the user's responsibility, and PL/I provides no assistance in maintaining it.

This option is valid only with DDM files.

To enable record-level locking, specify SHARE(ALL) and declare the file as an update file. This is recommended when running CICS applications.

The UNDEFINEDFILE condition is raised if the requested or default level of file sharing cannot be obtained.

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. This is the default.
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:

  set dd:sysprint=stdout:,SKIP0(Y)
  set dd:sysprint=con,SKIP0(Y)

TERMLBUF

The TERMLBUF option specifies the maximum number of lines in the window of a PL/I Presentation Manager (PM) terminal.

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

If the file is not associated with a PM terminal, the option is ignored. The default is 512 lines.

TYPE

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

Read syntax diagramSkip visual syntax diagram           .-CRLF-----.
>>-TYPE--(-+-LF-------+-)--------------------------------------><
           +-TEXT-----+
           +-FIXED----+
           +-VARLS----+
           +-VARLS4X4-+
           +-VARMS----+
           +-LL-------+
           +-LLZZ-----+
           +-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. See restrictions on ***) 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.

This is the default for ISAM and BTRIEVE.

LF
Specifies that records are delimited by the LF character combination. ('LF' represents the ASCII values of feed or '0A'x. See restrictions on ***) 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 CRLF.
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.

VARLS
Indicates that records have a two-byte prefix that specifies the number of bytes in the rest of the record and that the length prefix is held in littleendian format. These records look like NATIVE CHAR VARYING strings.

TYPE(VARLS) data sets provide the fastest way to use PL/I to read and write data sets containing records of variable length and arbitrary byte patterns. This is not possible with TYPE(CRLF) data sets because when a record is read that was written containing the bit string '0d0a'b4, a misinterpretation occurs.

VARLS4X4
Indicates that records have a four-byte prefix and a four-byte suffix. The prefix and suffix each contain the number of bytes in the rest of the record. This number is in NATIVE format and does not include either the four bytes used by the prefix or the four bytes used by the suffix.

Type(VARLS4X4) data sets provide a way to handle FORTRAN sequential unformatted files.

VARMS
Indicates that records have a two-byte prefix that specifies the number of bytes in the rest of the record and that the length prefix is held in bigendian format. These records look like NONNATIVE CHAR VARYING strings.

TYPE(VARMS) data sets provide a way to read SCALARVARYING files downloaded from the mainframe.

LL
Indicates that records have a two-byte prefix that specifies the total number of bytes in the record (including the prefix). The length is held in bigendian format.

TYPE(LL) data sets provide a way to read files downloaded from the mainframe with a tool (see VRECGEN.PLI sample program) that appends two bytes.

LLZZ
Specifies that records have a 4-byte prefix held the same way as varying records on S/390.

The LLZZ suboption provides a way to read and write data sets which contain records of variable length and arbitrary byte patterns which cannot be done with TYPE(CRLF) data sets. Under CRLF, a written record containing the bit string '0d0a'b4 is misinterpreted when it is read.

A TYPE(LLZZ) data set must not contain any record that is longer than the value determined for the record length of the data set.

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 non-print files with the TYPE(FIXED) attribute, SKIP is replaced by trailing blanks to the end of the line. If TYPE(CRLF) is being used, SKIP is replaced by CRLF with no trailing blanks.


Terms of use | Feedback

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