CRTDKTF (Create Diskette File)

CRTDKTF Command syntax diagram

 

Purpose

The Create Diskette File (CRTDKTF) command creates a diskette device file. The device file contains the file description, which identifies the device to be used and specifies the input and output data spooling requirements; the device file does not contain data. The diskette device file is used to read and write records on diskettes that are in the diskette device and that have been initialized in the basic, H, or I exchange format. The same device file is used for both input and output operations.

Note: This command is not used to create device files for use in save/restore operations. User-created device files are not needed for save/restore operations.

All the information in the diskette file description is contained in the command that creates it; there is no data description specifications (DDS) for diskette device files. The diskette file has only one record format for input/output operations. The record format consists of one character field containing the input data retrieved from the device or the output data written to the device. The program using the device file must describe the fields in the record format so that the program can arrange the data either received from or sent to the device in the manner specified by the diskette file description.

 

Required Parameters

FILE
Specifies the qualified name of the file being created. If the file is used by a high-level language (HLL) program, the file name must be consistent with the naming rules of that language; otherwise, the file must be renamed in the program.

The name of the diskette file can be qualified by one of the following library values:

*CURLIB: The diskette file is created in the current library for the job. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library where the diskette file is created.

diskette-device-file-name: Specify the name of the diskette device file being created.

 

Optional Parameters

DEV
Specifies the name of the diskette device used with this diskette device file to perform input/output data operations. The device name of the IBM-supplied diskette device description is QDKT. This parameter is ignored if SPOOL(*YES) is specified for the file when it is opened.

*NONE: No device name is specified. The name of the diskette device can be specified before the device file is opened, in a Change Diskette File (CHGDKTF) command or Override with Diskette File (OVRDKTF) command, or in the high-level language program that opens the file.

device-name: Specify the name of the device that is used with this diskette device file. The device name must already exist on the system as a device description before this device file is created.

VOL
Specifies one or more volume identifiers used by the file. More information on this parameter is in Commonly used parameters.

*NONE: The diskette volume identifiers are not specified for this file in this command. They can be specified later before the device file is opened, either in a Override with Diskette File (OVRDKTF) command or a Change Diskette File (CHGDKTF) command, or in the high-level language program. Otherwise, no volume identifier checking is done.

volume-identifier: Specify the identifiers of one or more volumes in the order in which they are put on the device and used. Each volume identifier contains a maximum of 6 alphanumeric characters. A blank is used as a separator character when listing multiple identifiers.

LABEL
Specifies the data file label of the data file on diskette that is used with this diskette device file. For input files (diskette input to system), this label specifies the identifier of the file that exists on the diskette. For output files (system output to diskette), the label specifies the identifier of the file that is created on the diskette. More information on this parameter is in Commonly used parameters.

*NONE: The data file label is not specified here. It can be specified before the device file is opened, in a CHGDKTF or OVRDKTF command, or in the high-level language program that opens the file.

data-file-label: Specify up to 8 characters for the identifier of the data file used with this diskette device file.

FILETYPE
Specifies whether the diskette device file being created describes data records or describes source records (statements) for a program or another file. More information on this parameter is in Commonly used parameters.

*DATA: The diskette file describes data records.

*SRC: The diskette file describes source records.

EXCHTYPE
Specifies, for diskette output files only, the exchange type used by the device file when the system is writing diskette data. More information on this parameter is in Commonly used parameters.

*STD: The basic exchange format is used for a type 1 or a type 2 diskette. The H exchange type is used for a type 2D diskette.

*BASIC: The basic exchange type is used.

*H: The H exchange type is used.

*I: The I exchange type is used.

CODE
Specifies the character code used. The code can be either extended binary-coded decimal interchange code (*EBCDIC) or the American National Standard Code for Information Interchange (*ASCII).

*EBCDIC: The extended binary-coded decimal interchange code (EBCDIC) character set code is used.

*ASCII: The ASCII character set code is used.

CRTDATE
Specifies the date when the diskette data file was created on the diskette.

Note: The creation date parameter is valid only for diskette input data files. If the creation date written on the diskette containing the data file does not match the date specified for the device file when it is opened, an error message is sent to the user program.

*NONE: The creation date is not specified. It is not checked unless it is supplied before the device file is opened, either in a OVRTAPF command or CHGTAPF command, or in the high-level language program.

creation-date: Specify the creation date of the data file used by this device file. The date must be specified in the format defined by the job attributes DATFMT and, if separators are used, DATSEP. However, the specified date is put in the diskette label in the format yymmdd.

EXPDATE
Specifies the expiration date. The files cannot be overwritten until the expiration date. The expiration date must be later than or equal to the current date.

*NONE: No expiration date for the data file is specified; the file is protected for 1 day. Its protection ends the day after it is created.

*PERM: The data file is permanently protected. An expiration date of 999999 is assigned.

expiration-date: Specify the expiration date of the data file. The date must be specified in the format defined by the job attributes DATFMT and, if separators are used, DATSEP. However, the specified date is put in the diskette label as yymmdd.

SPOOL
Specifies whether the input or output data for the diskette device file is spooled.

*NO: The data is not spooled. If this file is opened for input, the data is read directly from the diskette. If this is an output file, the data is written directly to the diskette as it is processed by the program.

Note: If SPOOL(*NO) is specified, the following parameters in this command are ignored: OUTQ, MAXRCDS, SCHEDULE, HOLD, SAVE, OUTPTY, and USRDTA.

*YES: The data is spooled. If this file is opened for input, an inline data file having the specified name is processed; otherwise, the next unnamed inline spooled file is processed. More information on named and unnamed inline files is in the Tape and Diskette Device Programming Link to PDF book. If this is an output file, the data is spooled for processing by a diskette or print writer.

OUTQ
Specifies the qualified name of the output queue.

The name of the output queue can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

QDKT: The spooled output data is sent to the IBM-supplied QDKT output queue. If no library qualifier is specified, *LIBL is used to find the output queue.

output-queue-name: Specify the name of the output queue to which the output data is spooled. The IBM-supplied output queue that is used by the diskette file is the QDKT output queue, stored in the QGPL library.

MAXRCDS
Specifies, for spooled files only, the maximum number of records in the spooled file for spooled jobs using this diskette device file.

100000: Up to 100,000 records are in the spooled file for the diskette data file that is produced by this device file.

*NOMAX: The system maximum is used.

maximum-records: Specify the maximum number of diskette records that are in the spooled file. Valid values range from 1 through 500000.

SCHEDULE
Specifies, for spooled output only, when the spooled file is available to a writer.

*FILEEND: The spooled file is made available to the writer as soon as the file is closed in the program.

*JOBEND: The spooled file is made available to the writer only after the entire job is completed.

*IMMED: The program does not wait; when the file is opened, an immediate allocation of the file resources is required.

HOLD
Specifies, for spooled output only, whether the spooled file is held. The spooled file can be released by using the Release Spooled File (RLSSPLF) command.

*NO: The spooled printer file is not held by the output queue. The spooled output is available to a writer based on the SCHEDULE parameter value.

*YES: The spooled file is held until released by the Release Spool File (RLSSPLF) command.

SAVE
Specifies, for spooled output only, whether the spooled file is saved (left on the output queue) after the output has been produced.

*NO: The spooled file data is not saved on the output queue after it has been produced.

*YES: The spooled file data is saved on the output queue until the file is deleted.

OUTPTY
Specifies the output priority for spooled output files that are produced by this job. The highest priority is 1 and the lowest priority is 9. More information on this parameter is in Commonly used parameters.

*JOB: The output priority associated with the job that created the spooled file is used.

output-priority: Specify the output priority. Valid values range from 1 (high priority) through 9 (low priority).

USRDTA
Specifies, for spooled output only, the user-specified data that identifies the file.

*BLANK: Ten blanks are used as the user data.

user-data: Specify up to 10 characters of text.

IGCDTA
Specifies whether the file processes double-byte character set (DBCS) data.

*NO: The file does not process DBCS data.

*YES: The file processes DBCS data.

WAITFILE
Specifies the number of seconds that the program waits for the file resources and session resources to be allocated when the file is opened, or for the device or session resources to be allocated when an acquire operation is performed to the file. If those resources are not allocated within the specified wait time, an error message is sent to the program. More information on this parameter is in Commonly used parameters.

Note: An immediate allocation of the device by the device resource is required when an acquire operation is performed to the file.

*IMMED: The program does not wait; when the file is opened, an immediate allocation of the file resources is required.

*CLS: The job default wait time is used as the wait time for the file resources being allocated.

number-of-seconds: Specify the number of seconds that the program waits for the file resources to be allocated to the diskette file when the file is opened, or the wait time for the device allocated when an acquire operation is performed to the file. Valid values range from 1 through 32767 seconds.

SHARE
Specifies whether the open data path (ODP) for the diskette file is shared with other programs in the routing step. When an ODP is shared, the programs accessing the file share facilities such as the file status and the buffer.

More information on shared database files is in the Database Programming topic in the Information Center.

*NO: The ODP created by the program with this attribute is not shared with other programs in the routing step. Every time a program opens the file with this attribute, a new ODP to the file is created and activated.

*YES: The ODP created with this attribute is shared with each program in the routing step that also specifies SHARE(*YES) when it opens the file.

Note: When SHARE(*YES) is specified and control is passed to a program, a read operation in that program retrieves the next input record. A write operation produces the next output record.

AUT
Specifies the authority given to users who do not have specific authority to the diskette file, who are not on an authorization list, and whose user group has no specific authority to the diskette file. More information on this parameter is in Commonly used parameters.

*LIBCRTAUT: The public authority for the diskette file is taken from the value on the CRTAUT parameter of the target library (the library that is to contain the diskette file). The public authority is determined when the diskette file is created. If the CRTAUT value for the library changes after the diskette file is created, the new value does not affect any existing objects.

*CHANGE: The user can perform all operations on the diskette file except those limited to the owner or controlled by object existence authority and object management authority. The user can change and perform basic functions on the diskette file. Change authority provides object operational authority and all data authority.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the diskette file.

*USE: The user can perform basic operations on the diskette file, such as running a program or reading a file. The user cannot change the diskette file. *USE authority provides object operational authority, read authority, and execute authority.

*EXCLUDE: The user cannot access the diskette file.

authorization-list-name: Specify the name of the authorization list used.

REPLACE
Specifies whether an existing file is replaced by the new diskette file. More information on this parameter is in Commonly used parameters.

*YES: The existing diskette file is replaced by the one being created.

*NO: The existing file, if any, is not replaced by the diskette file.

TEXT
Specifies text that briefly describes the diskette device file. More information on this parameter is in Commonly used parameters.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Examples for CRTDKTF

Example 1: Creating Diskette Device File 

CRTDKTF   FILE(DSPHST)

This command creates a diskette device file named DSPHST. The defaults for all the other parameters are assumed. The device name, diskette volume, file label, and the creation date of the data file on diskette must be specified in another CL command or in each program that uses the device file. The device file describes diskette data files that are in EBCDIC code and that are spooled for both input and output. Output goes to the QDKT output queue and then onto diskette as soon as the file is closed by the program. When output is produced from the output queue, only one copy is produced.

Example 2: Specifying DBCS Data Processing 

CRTDKTF   FILE(IGCLIB/IGCDKT) IGCDTA(*YES)

This command creates a diskette device file named IGCDKT, which is stored in the library IGCLIB, and it can process double-byte character set (DBCS) data.

Error messages for CRTDKTF

*ESCAPE Messages

CPF7302
File &1 not created in library &2.