Create Display File (CRTDSPF)

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.

Parameters

Keyword	Description	Choices	Notes
FILE	File	Qualified object name	Required, Positional 1
	Qualifier 1: File	Name
	Qualifier 2: Library	Name, *CURLIB
SRCFILE	Source file	Single values: NONE Other values: Qualified object name*	Optional, Positional 2
	Qualifier 1: Source file	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
SRCMBR	Source member	Name, *FILE	Optional, Positional 3
GENLVL	Generation severity level	0-30, 20	Optional
FLAG	Flagging severity level	0-30, 0	Optional
DEV	Display device	Single values: NONE Other values (up to 50 repetitions): Name, REQUESTER	Optional
IGCDTA	User specified DBCS data	NO, YES	Optional
IGCEXNCHR	DBCS extension characters	YES, NO	Optional
TEXT	Text 'description'	Character value, SRCMBRTXT, BLANK	Optional
OPTION	Source listing options	Values (up to 4 repetitions): SRC, NOSRC, SOURCE, NOSOURCE, LIST, NOLIST, SECLVL, NOSECLVL, EVENTF, NOEVENTF	Optional, Positional 4
MAXDEV	Maximum devices	1-256, 1	Optional
ENHDSP	Enhanced display	YES, NO	Optional
RSTDSP	Restore display	NO, YES	Optional
DFRWRT	Defer write	YES, NO	Optional
CHRID	Character identifier	Single values: DEVD, SYSVAL, JOBCCSID, CHRIDCTL Other values: Element list	Optional
	Element 1: Graphic character set	Integer
	Element 2: Code page	Integer
DECFMT	Decimal format	FILE, JOB	Optional
SFLENDTXT	SFLEND text	FILE, MSG	Optional
WAITFILE	Maximum file wait time	Integer, IMMED, CLS	Optional
WAITRCD	Maximum record wait time	Integer, NOMAX, IMMED	Optional
DTAQ	Data queue	Single values: NONE Other values: Qualified object name*	Optional
	Qualifier 1: Data queue	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
SHARE	Share open data path	NO, YES	Optional
SRTSEQ	Sort sequence	Single values: JOB, LANGIDSHR, LANGIDUNQ, HEX Other values: Qualified object name	Optional
	Qualifier 1: Sort sequence	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
LANGID	Language ID	Character value, *JOB	Optional
LVLCHK	Record format level check	YES, NO	Optional
AUT	Authority	Name, LIBCRTAUT, ALL, CHANGE, EXCLUDE, *USE	Optional
REPLACE	Replace file	YES, NO	Optional

Top

File (FILE)

Specifies the display device file to be created.

If the display device file is used in a high-level language program, the file name should be consistent with the naming rules of that language. Otherwise, the file must be renamed in the program.

This is a required parameter.

Qualifier 1: File

name: Specify the name of the display file to be created.

Qualifier 2: Library

*CURLIB: The current library for the job is used to locate the display device file. If no library is specified as the current library for the job, QGPL is used.
name: Specify the library where the display file is created.

Source file (SRCFILE)

Specifies the source file (if specified) containing the data description specifications (DDS) source used to create the display device file.

Single values

*NONE: There is no DDS source for this display device file.

Qualifier 1: Source file

name: Specify the name of the source file that contains the DDS used to create the display device file.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB: The current library for the job is used to locate the file. If no library is specified as the current library for the job, QGPL is used.
name: Specifies the library where the file is located.

Generation severity level (GENLVL)

Specifies the severity level of data description specifications (DDS) messages that cause file creation to fail. This parameter applies only to messages created while processing DDS source files.

20: If errors occur in the DDS source file processing with a severity level greater than or equal to 20, the file is not created.
0-30: Specify the desired severity level value. If 0 is specified, the file is not created. The value specified must be greater than or equal to the value specified for the Flagging severity level (FLAG) parameter.

Display device (DEV)

Specifies the names of one or more display devices that are used with this display file to pass data records between the users of the display devices and their jobs.

Single values

*NONE: No display device name is specified. The name of the display device must be specified later in a Change Display File (CHGDSPF) command or Override with Display File (OVRDSPF) command, or in the high-level language program that opens the file.

Other values (up to 50 repetitions)

*REQUESTER: The display device from which the program is called is the device assigned to the file when the file is opened.

name: Specify the names of one or more display devices. *REQUESTER can be specified as one of the names. A maximum of 50 device names (including *REQUESTER) can be specified, but the total number cannot exceed the number specified for the Maximum devices (MAXDEV) parameter when the file is opened.

User specified DBCS data (IGCDTA)

Specifies, for program-described files, whether the file processes double-byte character set (DBCS) data. Specifies, for externally described files, the DBCS attributes of the file.

For program-described files

*NO: The file does not process double-byte character set (DBCS) data.

*YES: The file processes double-byte character set (DBCS) data.

For externally-described files

*NO: The only double-byte character set (DBCS) attributes of the file are those specified in the data description specifications (DDS).
*YES: DBCS attributes, in addition to those specified in the DDS, include: (1) putting the DDS keyword for alternative data type (IGCALTTYP) into effect and (2) identifying DBCS attributes of fields, values, or messages.

DBCS extension characters (IGCEXNCHR)

Specifies whether the system processes double-byte character set (DBCS) extended characters. When processing DBCS extended characters, the device requires the assistance of the system. The system must tell the device what the character looks like before the device can display or print the character. Extended characters are stored in a DBCS font table, not in the DBCS device. Extended character processing is a function of the operating system that is required to make characters stored in a DBCS font table available to a DBCS device.

*YES: The system processes DBCS extended characters.
*NO: The system does not process DBCS extended characters; it displays extended characters as the undefined character.

Source listing options (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 first value listed for the option is used.

Note: The first values on each option are similar to, but are not actually default values, and therefore, cannot be changed with the CHGCMDDFT (Change Command Default) command.

Source Listing Option

*SRC or *SOURCE: A printout of the source statements, including a list of errors, 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 keyword or record format that caused the error.

Program Listing Option

*LIST: An expanded source printout is created, showing a detailed list of the file specifications and the references to other file descriptions.

*NOLIST: The expanded source printout is not created.

Second-Level Message Text Option

*NOSECLVL: The messages section of the data description specifications (DDS) printout does not contain the online help information for messages issued during DDS processing.
*SECLVL: The online help information appears in the DDS printout.

Event File Creation Option

*NOEVENTF: The compiler does not produce an event file for the CoOperative Development Environment (CODE) product.
*EVENTF: The compiler produces an event file that can be used by the CODE product. The event file is created as a member in the file EVFEVENT in your object library. The CODE product uses this file to offer error feedback integrated with the CODE editor. This value is normally specified by the CODE product on your behalf.

Enhanced display (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.

Restore display (RSTDSP)

Specifies whether data being shown at a display device 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.
*YES: The data being shown when this file is suspended is saved, and it is restored to the device display when the file is used again.

Character identifier (CHRID)

Specifies the type of character conversions that may occur for the display file. When necessary, the system converts character data sent to and received from the device. This ensures that the correct hexadecimal byte values of characters are sent to the device and are returned to the application program.

Single values

*DEVD: Specifies the CHRID of the device is used to represent the CCSID of the field data for every named field with the CHRID DDS keyword. No conversion will ever occur since the CCSID of the field data will always be the same as the CHRID of the device.
*SYSVAL: Specifies the QCHRID system value is used to represent the CCSID of the field data for every named field with the CHRID DDS keyword. Conversion will only occur for these specific fields when CCSID of the field data is different than the CHRID of the device.
*JOBCCSID: Specify character conversion occurs when a difference exists between the device CHRID, job CCSID or display file CCSID values. On input, character data is converted from the device CHRID to the job CCSID when necessary. On output, character data is converted from the job CCSID to the device CHRID when necessary. On output, constant character data in the display file is converted from the display file CCSID to the device CHRID when necessary.
Note: The *JOBCCSID special value, either specified directly on the CHRID command parameter or on the CHRIDCTL job attribute when the *CHRIDCTL special value is specified for the CHRID command parameter, is not allowed if the file was created on a system at an earlier release level than V2R3M0. A file created prior to V2R3M0 will not be tagged with a CCSID and can not be used in combination with the *JOBCCSID support.
*CHRIDCTL: Specifies that the system checks the CHRIDCTL job attribute to determine whether to use the *JOBCCSID or *DEVD special values on the CHRID command parameter for this display file.

Element 1: Graphic character set

integer: Specify the number of the graphic character set to be used. Valid values range from 1 through 32767.

Element 2: Code page

integer: Specify the number of the code page to be used. Valid values range from 1 through 32767.

Note: The graphic character set and code page specifies the value used to represent the CCSID of the field data for every named field with the CHRID DDS keyword. Conversion will only occur for these specific fields when CCSID of the field data is different than the CHRID of the device.

SFLEND text (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.

Maximum file wait time (WAITFILE)

Specifies the number of seconds that the program waits for the file resources to be allocated when the file is opened, or the device or session resources to be allocated when an acquire operation is performed to the file. If the file resources cannot be allocated in the specified wait time, an error message is sent to the program.

*IMMED: The program does not wait. Immediate allocation of file resources is required.

*CLS: The job default wait time is used as the wait time for the file resources to be allocated.
1-32767: Specify the number of seconds to wait for file resources to be allocated.

Maximum record wait time (WAITRCD)

Specifies the number of seconds the program waits for the completion of a read-from-invited-devices operation to a multiple device file in a high-level language program. Refer to the 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 the input form all invited devices currently accessing the file. If a record is not returned from any of the invited program devices 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 single device.

*NOMAX: There is no limit on the time the system waits for the completion of the operation.

*IMMED: The program does not wait. If a record is not available when the read-from-invited-devices operation is done, a notify message is sent to the program.

integer: Specify the maximum number of seconds that the program waits. Valid values range from 1 through 32767 seconds.

Data queue (DTAQ)

Specifies the data queue on which entries are placed. The specified data queue must have a minimum length of 80 characters. The data queue need not exist when the display file is created since the name specified for this parameter is not evaluated until the file is used.

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.

Single values

*NONE: No data queue is specified.

Qualifier 1: Data queue

name: Specify the name of the data queue on which entries are placed.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread are searched until the first match is found.

*CURLIB: The current library is used to locate the data queue. If no library is specified as the current library for the job, QGPL is used.
name: Specify the library where the data queue is located.

Sort sequence (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.

Single values

*JOB: The SRTSEQ value specified on the job attribute is used.
*LANGIDSHR: The sort sequence table can contain the same weight for multiple characters, and is the shared weighted table associated with the language specified in 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, and the hexadecimal values of the characters are used to determine the sort sequence.

Qualifier 1: Sort sequence

name: Specify the name of the sort sequence table to be used.

Qualifier 2: Library

*LIBL: All libraries in the library list for the current thread 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.
name: Specify the name of the library to be searched.

Language ID (LANGID)

Specifies the language identifier used when *LANGIDSHR or *LANGIDUNQ is specified for the Sort sequence (SRTSEQ) parameter. The language identifier is used with the SRTSEQ parameter to determine which sort sequence table the file uses.

*JOB: The language identifier specified for the job is used.

character-value: Specify a language identifier. To see a complete list of identifiers when prompting this command, position the cursor on the field for this parameter and press F4 (Prompt).

Authority (AUT)

Specifies the authority you are giving to users who do not have specific authority for the object, who are not on an authorization list, and whose group profile or supplemental group profiles do not have specific authority for the object.

*LIBCRTAUT: The system determines the authority for the object by using the value specified for the Create authority (CRTAUT) parameter on the Create Library command (CRTLIB) for the library containing the object to be created. If the value specified for the CRTAUT parameter is changed, the new value will not affect any existing objects.

*CHANGE: The user can perform all operations on the object except those limited to the owner or controlled by object existence (*OBJEXIST) and object management (*OBJMGT) authorities. The user can change and perform basic functions on the object. *CHANGE authority provides object operational (*OBJOPR) authority and all data authority. If the object is an authorization list, the user cannot add, change, or remove users.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management (*AUTLMGT) 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 object.

*USE: The user can perform basic operations on the object, such as running a program or reading a file. The user cannot change the object. Use (*USE) authority provides object operational (*OBJOPR), read (*READ), and execute (*EXECUTE) authorities.

*EXCLUDE: The user cannot access the object.

name: Specify the name of an authorization list to be used for authority to the object. Users included in the authorization list are granted authority to the object as specified in the list. The authorization list must exist when the object is created.

Replace file (REPLACE)

Specifies whether an existing file, other than a save or database file, is replaced.

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

Note: The authority value for the file is determined by the user profile of the user. If an existing file is replaced, the authority value for the new file is copied from the replaced file.

*YES: An existing file is replaced if the creation of the new display device file with the same name and library is successful.
*NO: The creation of a new display device file is not allowed if there is an existing display device file with the same name and library.

Examples

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.