CRTDSPF

CRTDSPF (Create Display File)

CRTDSPF Command syntax diagram

Purpose

The Create Display File (CRTDSPF) command creates a display device file. The device file contains the file description, which identifies the device used and, optionally, the record formats used by the device (if specified in data description specifications (DDS)); the device file does not contain data. The display device file sends records to one or more display devices associated with the device file, and to receive records from the display devices.
The display file description contains of information that is specified in two places: (1) in the source file that contains the DDS (if used); and (2) in the CRTDSPF command. The DDS contains the specifications for each record format in the device file and for the fields in each record format.
The Change Display File (CHGDSPF) or Override Display File (OVRDSPF) command is used in a program to change or override the parameter values specified in the display file description; the override command must be run before the display file is opened by the program. Overridden values are changed only for the running of the program; once the program ends, the original parameter values specified for the display file are used.

Note: If an application program attempts to acquire a work station on a switched line and the line connection has been lost or has never been established, the application program waits indefinitely until the connection is established.

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 file can be qualified by one of the following library values:

*CURLIB: The 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 file is created.

display-device-file-name: Specify the name of the display device file.

Optional Parameters

SRCFILE

Specifies the qualified name of the source file (if specified) that contains the DDS for the records in the display device file. More information on the specifications stated in DDS is in the Application Display Programming
book and the DDS Reference topic in the Information Center.
*NONE: There is no DDS source file for this display device file; either the display device file has only one record format with no fields, or the program that uses the file must describe the record formats and their fields.
The name of the source file 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.

source-file-name: Specify the name of the source file that contains the DDS for this display device file.

SRCMBR

Specifies the name of the member in the source file that contains the DDS for this display device file. The SRCMBR parameter is valid only if SRCFILE is specified.
*FILE: The source file member name is the same as the device file name specified in the FILE parameter.
source-file-member-name: Specify the name of the member in the source file specified by SRCFILE that is used to create the display device file.

OPTION

Specifies the type of output produced when the file is created. A maximum of four of the following values can be specified in any order on this parameter. If neither or both of the values on an option are specified, the underlined value is used.

Note: The underlined values for this parameter are similar to, but not actually default values, and therefore, cannot be changed with the CHGCMDDFT (Change Command Default) command.

Source Listing Options
*SRC or *SOURCE: A printout of the source statements used to create the file and errors that occur is created.
*NOSRC or *NOSOURCE: No printout of the source statements is created unless errors are detected. If errors are detected, they are listed along with the record format containing the error.
Program Listing Options
*LIST: An expanded source printout is created, showing a detailed list of the file specifications that result from the source statements and references to other file descriptions.
*NOLIST: An expanded source printout is not created.
Second-Level Message Text Options
*NOSECLVL: The messages section of the data description specifications (DDS) listing does not contain the second-level message text for the errors found during DDS processing.
*SECLVL: Second-level message text is included in the source listing.
Event File Creation Options
*NOEVENTF: The compiler does not produce an event file for the CoOperative Development Environment/400 (CODE/400) product.
*EVENTF: The compiler produces an event file that can be used by the CODE/400 product. The event file is created as a member in the file EVFEVENT in your object library. The CODE/400 product uses this file to offer error feedback integrated with the CODE/400 editor. This value is normally specified by the CODE/400 product on your behalf.

GENLVL

Specifies the severity level at which the create operation fails. If errors occur that have a severity level greater than or equal to this value, the operation ends.

Note: This parameter applies only to messages created while processing DDS source statements. Messages created elsewhere in the file creation process are not affected by this parameter.

20: If errors occur in the DDS source with a severity level greater than or equal to 20, the file is not created.
severity-level: Specify a severity level ranging from 0 through 30. The file is not created if the severity level specified for this parameter equals 0 or is less than the severity level that occurs in the data description specifications (DDS) source. This value must be greater than or equal to value specified on the FLAG parameter.

FLAG

Specifies the minimum severity level of messages to be listed in the DDS source listing.
0: The spooled file is owned by the original user profile of the job. If the job has switched to a new user profile, the original user profile is still the owner of the spooled file.
severity-level: Specify the minimum severity level of messages to be listed. Valid values range from 0 through 30. The severity level specified must be less than or equal to the severity level specified on the GENLVL parameter.

DEV

Specifies the names of one or more display devices used with this display device file to pass data records between the users of the display devices and their jobs. The device name specified in the display device file supplied by IBM is *REQUESTER.
*REQUESTER: The device from which the program is called is assigned to the file when the file is opened.
device-name: Specify the names of one or more display devices used with this device file to pass data records between the users of the devices and the system. Each device name must already be known on the system by a device description before this device file is created. *REQUESTER can be specified as one of the names. Up to 50 names can be specified in this command, but the total number cannot exceed the number specified on the MAXDEV parameter.
*NONE: No device name is specified. The name of the display device must be specified later in a CHGDSPF or OVRDSPF command, or in the HLL program that opens the file.

MAXDEV

Specifies the maximum number of display devices that are connected to the display device file at the same time, while the file is open. However, if a CL program is written to get access to more than one work station through the same file (through a single running of the program), this parameter must specify a value greater than 1.
The names of the devices are specified in the DEV parameter of this command, in a later CHGDSPF or OVRDSPF command, or in the HLL program that opens the file.
1: Only one device name, or *REQUESTER, can be specified for this display device file.
number-of-devices: Specify the maximum number of devices that are connected to this display file at the same time. Valid values range from 1 through 256.

ENHDSP

Specifies whether the data being shown at a display station by this display file is using the enhanced capabilities available on the display station.
*YES: The data for the display file is shown using any enhanced capabilities available on the display station. These capabilities can include mnemonics, selection cursor, and graphical window borders.
*NO: The data for this display file is shown as it would be on a 5250 display station. No enhanced capabilities that are available on the display, such as mnemonics, selection cursor, or graphical window borders, are used. This value is normally used to preserve character-based interaction across all display stations.

RSTDSP

Specifies whether data being shown on a display by this display file is saved at the time the file is suspended (made temporarily inactive) so that another display file can show different data on the same device. If the data for this file is saved, it is restored to the display of the device when the file is used again.
*NO: The data being shown by this file is not saved when the file is suspended. When control is returned to the programs using this file, the data is not restored.
*YES: The data being shown when the file is suspended is saved so it can be shown on the display when the file is used again.

DFRWRT

Specifies that the writing of data is deferred (delayed) until it is written out with other data when a read request is made. Control is returned to the program immediately after the data is received. This may result in improved performance.
*YES: When the program issues a write request, control is returned after the buffer is processed. The data may not be shown immediately; the actual display of the data may take place later when a read or combined write/read operation is performed. The buffer is then available to be prepared for the next read or combined write/read operation.
*NO: After a write operation, the user program does not regain control until the input/output operation is completed (with the data displayed and the input/output feedback information available).

CHRID

Specifies the character identifier (graphic character set and code page) that a work station display device supports. When a display file that was created with the CHRID DDS keyword is used with the device, the system converts data sent to and received from the device to ensure that the correct characters are shown and that the correct hexadecimal byte values are returned to the application program. More information about display file CHRID processing and the translation tables that are used to convert data sent to and received from the display are in the Application Display Programming book.
*DEVD: The value specified on the CHRID parameter in the device description of the work station on which the application is running, is used. If no CHRID value is specified, the QCHRID system value for the system on which the application is running, is used. No conversion is necessary because the file has the same character identifier as the work station. For a list of valid values, see the table in CHRID description of the CRTDEVDSP command.
*SYSVAL: The system determines the graphic character set and code page values for the command parameters from the QCHRID system values.
*JOBCCSID: The character data is converted, if necessary, from the device CHRID to the CCSID (coded character set identifier) of the job during input, and from the CCSID of the job to the device CHRID on output.
*CHRIDCTL: The system checks the CHRIDCTL job definition attribute to determine whether to use *JOBCCSID or *DEVD on the CHRID command parameter for this file.
Element 1: Character Set
graphic-character-set: Specify the graphic character set values that match the attributes of the display device. Valid values range from 1 through 32767.
Element 2: Code Page
code-page: Specify the code page set values that match the attributes of the display device. Valid values range from 1 through 32767.

DECFMT

Specifies which decimal format value is used when editing numeric fields with the EDTCDE DDS keyword. The decimal format value determines the use of commas and periods for the decimal position and three digit positional separators on edited fields.
*JOB: Use the decimal format value from the DECFMT job attribute when the file is opened.
*FILE: Use the decimal format value stored with the file when the file was created.

SFLENDTXT

Specifies where the 'More...' and 'Bottom' text is retrieved from when displaying a subfile. The 'More...' and 'Bottom' text is displayed in a subfile when the SFLEND(*MORE) DDS keyword is specified on the subfile control record.
*MSG: Use the 'More...' and 'Bottom' text retrieved from messages CPX6AB1 and CPX6AB2 which exist in the current active language of the system when the file is opened.
*FILE: Use the 'More...' and 'Bottom' text that is stored in the file during file creation. This text was retrieved from messages CPX6AB1 and CPX6AB2 which exist in the active language of the system when the file was created.

IGCDTA

Specifies, for program-described original files, whether the file processes double-byte character set (DBCS) data. For externally described printer files, this parameter specifies DBCS attributes of the file.
*NO: The file does not process DBCS data.
*YES: The file processes DBCS data.

RTNDTACAK

Specifies whether AID keys which do not return data, like CA keys, the print, help, home, and clear keys, will allow input data to be returned from the device to the application after validity checking has caused the input buffer to be updated.
*NO: The input buffer will be restored to its original values before it is returned to the application. Any date, time, or timestamp field which has invalid data is replaced in the input buffer with a valid default value.
*YES: The input buffer, which may include values that did not pass the validity checks, will be returned to the application. Any date, time, or timestamp field which has invalid data is replaced in the input buffer with a valid default value.

IGCEXNCHR

Specifies whether the system processes double-byte character set (DBCS) extension characters.
*YES: The system processes DBCS extension characters.
*NO: The system does not process DBCS extension characters; it displays extension characters as the undefined character.

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 display device 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.

WAITRCD

Specifies the number of seconds the program waits for the completion of a read-from-invited-device operation to a multiple device file in a high-level language program. Refer to the appropriate high-level language reference manual to determine when a file is treated as a multiple device file. The program performing the read operation waits for input from all invited devices currently accessing the file. If a record is not returned from an invited device in the specified amount of time, a notify message is sent to the program. This parameter has no effect on an input operation directed to a specific device.

Note: This parameter is also used to specify the time (seconds) that a CL program waits to complete a WAIT command. If a record is not returned from any of the devices that should return a record, an escape message is sent to the CL program. More information on the WAITRCD parameter is in the Receive File (RCVF), Send File (SNDF), Send/Receive File (SNDRCVF), and WAIT (Wait) command descriptions.

*NOMAX: There is no limit on the time the system waits for the completion of the operation.
*IMMED: The program does not wait for the read-from-invited-device operation for the completion of the file. A record must be available from an invited program device when the read-from-invited-program-device operation is performed. If a record is not already available when the read-from-invited-program-device operation is performed, a notify message is sent to the program.
number-of-seconds: Specify the number of seconds that the program waits for the completion of the read-from-invited-device operation. Valid values range from 1 through 32767.

DTAQ

Specifies the name of the data queue that receives an entry from the system when a data-available event is signaled from an invited display device. The data queue need not exist when the display file is created since the name specified on this parameter is not evaluated until the file is used. More information on the data queue function is in the CL Programming book.

Note: Keyed data queues are not supported for this parameter. If a keyed data queue is specified, a run-time error will occur; but because it is not required that a data queue exist at the time the command is issued, the error will not be flagged.

*NONE: A data queue does not receive an entry from the system.
The name of the data 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.

data-queue-name: Specify the name of the data queue that is to receive an entry from the system when the data-available event is signaled.

SHARE

Specifies whether the open data path (ODP) for the display 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.

SRTSEQ

Specifies the sort sequence used for this user profile. The sort sequence is used in conjunction with the LANGID parameter to determine which sort sequence table is used.
*JOB: The SRTSEQ value specified on the job attribute is used.
*LANGIDSHR: The sort sequence table uses the same weight for multiple characters, and is the shared-weight sort sequence table associated with the language specified on the LANGID parameter.
*LANGIDUNQ: The sort sequence table must contain a unique weight for each character in the code page.
*HEX: A sort sequence table is not used. The hexadecimal values of the characters are used to determine the sort sequence.
The name of the sort sequence table 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.

table-name: Specify a table name.

LANGID

Specifies the language identifier used when *LANGIDSHR or *LANGIDUNQ is specified on the SRTSEQ parameter. The language identifier is used with the SRTSEQ parameter to determine which sort sequence table the file uses.
*JOB: The language ID specified in the job description is used.
language-id: Specify a language identifier to be used by the file.

LVLCHK

Specifies whether the record format level identifiers in the program are checked against those in the device file when the file is opened. If so, the record format identifiers in the program must match those in the device file. Because the same record format name can exist in more than one file, each record format is given an internal system identifier when it is created.
*YES: The level identifiers of the record formats are checked when the file is opened. If the level identifiers do not match, an error message is sent to the program that requested the open, and the file is not opened.
*NO: The level identifiers are not checked when the file is opened.

AUT

Specifies the authority given to users who do not have specific authority to the display file, who are not on an authorization list, and whose user group has no specific authority to the display file. More information on this parameter is in Commonly used parameters.
*LIBCRTAUT: The public authority for the display file is taken from the value on the CRTAUT parameter of the target library (the library that is to contain the display file). The public authority is determined when the display file is created. If the CRTAUT value for the library changes after the display file is created, the new value does not affect any existing objects.
*CHANGE: The user can perform all operations on the display 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 display 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 display file.
*USE: The user can perform basic operations on the display file, such as running a program or reading a file. The user cannot change the display file. *USE authority provides object operational authority, read authority, and execute authority.
*EXCLUDE: The user cannot access the display file.
authorization-list-name: Specify the name of the authorization list used.

REPLACE

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

Note: The existing file cannot be replaced if it is in use by this job or another job.

*YES: The existing display file is replaced by the one being created.
*NO: The existing file, if any, is not replaced by the display file.

TEXT

Specifies the text that briefly describes the display device file. More information on this parameter is in Commonly used parameters.
*SRCMBRTXT: The text is taken from the source file member used to create the printer file. If the source file is a database file, the text is taken from the source member. If the source file is an inline file or a device file, the text is blank.
*BLANK: Text is not specified.
'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Examples for CRTDSPF
Example 1: Specifying Default Optional Parameters
CRTDSPF FILE(DSPHIST) SRCFILE(PRSNNL/JOBHIST)

This command creates a display device file named DSPHIST which is stored in the current library using the source file named JOBHIST that is stored in the PRSNNL library. The defaults for all the other parameters are assumed. Only the device requesting the program that uses this device file (that is, *REQUESTER) is assigned to the device file. The level identifiers of the record formats are checked when the file is opened. The public has only object operational authority for the device file.
Example 2: Specifying DBCS Data Processing
CRTDSPF FILE(IGCDSP) SRCFILE(IGCLIB/IGCSRC) IGCDTA(*YES)

This command creates the display file IGCDSP from the source file IGCSRC in the library IGCLIB. The file processes double-byte character set (DBCS) data.
Error messages for CRTDSPF
*ESCAPE Messages

CPF7302

File &1 not created in library &2.