Change Display File (CHGDSPF)

Parameters

Keyword	Description	Choices	Notes
FILE	File	Qualified object name	Required, Key, Positional 1
	Qualifier 1: File	Generic name, name, *ALL
	Qualifier 2: Library	Name, LIBL, CURLIB, ALL, ALLUSR, *USRLIBL
DEV	Display device	Single values: SAME, NONE Other values (up to 50 repetitions): Name, *REQUESTER	Optional, Positional 2
MAXDEV	Maximum devices	1-256, *SAME	Optional
LVLCHK	Record format level check	SAME, YES, *NO	Optional
TEXT	Text 'description'	Character value, SAME, BLANK	Optional
ENHDSP	Enhanced display	SAME, YES, *NO	Optional
RSTDSP	Restore display	SAME, NO, *YES	Optional
DFRWRT	Defer write	SAME, YES, *NO	Optional
CHRID	Character identifier	Single values: SAME, DEVD, SYSVAL, JOBCCSID, CHRIDCTL Other values: Element list*	Optional
	Element 1: Graphic character set	Integer
	Element 2: Code page	Integer
DECFMT	Decimal format	SAME, FILE, *JOB	Optional
SFLENDTXT	SFLEND text	SAME, FILE, *MSG	Optional
IGCDTA	User specified DBCS data	SAME, NO, *YES	Optional
IGCEXNCHR	DBCS extension characters	SAME, YES, *NO	Optional
WAITFILE	Maximum file wait time	Integer, SAME, CLS, *IMMED	Optional
WAITRCD	Maximum record wait time	Integer, SAME, IMMED, *NOMAX	Optional
DTAQ	Data queue	Single values: SAME, NONE Other values: Qualified object name	Optional
	Qualifier 1: Data queue	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
SHARE	Share open data path	SAME, NO, *YES	Optional

Top

File (FILE)

Specifies the display device file to be changed.

This is a required parameter.

Qualifier 1: File

*ALL: All of the display device files are changed in the specified libraries.
generic-name: Specify the generic name of the display files to be changed. A generic name is a character string that contains one or more characters followed by an asterisk (*).
name: Specify the name of the display file to be changed.

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 thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.

*USRLIBL: If a current library entry exists in the library list for the current thread, the current library and the libraries in the user portion of the library list are searched. If there is no current library entry, only the libraries in the user portion of the library list are searched.

*ALLUSR

All user libraries are searched. All libraries with names that do not begin with the letter Q are searched except for the following:

#CGULIB     #DSULIB     #SEULIB
#COBLIB     #RPGLIB
#DFULIB     #SDALIB

Although the following Qxxx libraries are provided by IBM, they typically contain user data that changes frequently. Therefore, these libraries are considered user libraries and are also searched:

QDSNX       QRCLxxxxx   QUSRIJS     QUSRVxRxMx
QGPL        QSRVAGT     QUSRINFSKR
QGPL38      QSYS2       QUSRNOTES
QMGTC       QSYS2xxxxx  QUSROND
QMGTC2      QS36F       QUSRPOSGS
QMPGDATA    QUSER38     QUSRPOSSA
QMQMDATA    QUSRADSM    QUSRPYMSVR
QMQMPROC    QUSRBRM     QUSRRDARS
QPFRDATA    QUSRDIRCL   QUSRSYS
QRCL        QUSRDIRDB   QUSRVI

'xxxxx' is the number of a primary auxiliary storage pool (ASP).
A different library name, in the format QUSRVxRxMx, can be created by the user for each previous release supported by IBM to contain any user commands to be compiled in a CL program for the previous release. For the QUSRVxRxMx user library, VxRxMx is the version, release, and modification level of a previous release that IBM continues to support.

*ALL: All libraries in the system, including QSYS, are searched.

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

Display device (DEV)

Specifies the names of one or more display devices that are 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.

Single values

*SAME: The display device names do not change.
*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.

Maximum devices (MAXDEV)

Specifies the maximum number of display devices that can be 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.

*SAME: The maximum number of display devices that can be connected to the display device file does not change.
1-256: Specify the maximum number of display devices that can be connected to this display device file at the same time.

Record format level check (LVLCHK)

Specifies whether the level identifiers of the record formats in this device file are checked when the file is opened by a program. 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.

*SAME: The value does not change.
*YES: The level identifiers are checked when the file is opened. If the level identifiers do not all match, an error message is sent to the program that requested opening of the file.

*NO: The level identifiers are not checked when the file is opened.

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.

*SAME: This value does not change.
*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 a different display file can be used to 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.

*SAME: The value does not change.
*NO: The data being shown by this file is not saved when the file is suspended.
*YES: The data being shown when the file is suspended is saved so it can be restored to the display of the device when the file is used again.

Defer write (DFRWRT)

Specifies that the writing of data is delayed until it can be shown 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.

*SAME: The value specified in the device file does not change.
*NO: After a write operation, the user program does not regain control until the input/output operation is completed.
*YES: When the program issues a write request, control is returned to that program 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.

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

*SAME: The value does not change.
*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.

*SAME: The SFLEND text value does not change.
*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.
*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.

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

*SAME: The value does not change.
*NO: The file does not process double-byte character set (DBCS) data.
*YES: The file processes DBCS data.

For externally-described files

*SAME: The value does not change.
*NO: The DBCS attributes of the file are defined in the data description specifications (DDS).
*YES: DBCS attributes, in addition to those defined in the DDS, include (1) putting the DDS keyword IGCALTTYP into effect, and (2) identifying DBCS attributes of fields or messages in the DDS.

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.

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

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. If the file resources cannot be allocated within the specified wait time, an error message is sent to the program.

*SAME: The wait time does not change.

*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.

*SAME: The wait record value does not change.
*NOMAX: There is no limit on the amount of time the program waits for completion of the read-from-invited device 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.

1-32767: Specify the number of seconds that the program waits for completion of the read-from-invited-device operation.

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

*SAME: The data queue name does not change.
*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 for the thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.

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

Share open data path (SHARE)

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

*SAME: The value does not change.

*NO: The ODP is not shared with other programs in the routing step. A new ODP for the file is created and used every time a program opens the file.

*YES: The same ODP is shared with each program in the job that also specifies *YES when it opens the file.

Examples

Example 1: Specifying Multiple Display Devices

CHGDSPF   FILE(ORDENT)  DEV(WS1 WS2 WS3)  MAXDEV(3)

This command changes the description of the display device file named ORDENT. The file is located through the library list. The devices used with this file are the work stations WS1, WS2, and WS3. All three of the devices can be used at the same time with this display file.

Example 2: Delaying Writing of Data

CHGDSPF   FILE(ACCREC/*ALL)  DFRWRT(*YES)

This command changes the description of all display files in library ACCREC to delay writing data until a read request is made.

Example 3: Specifying DBCS Data Processing

CHGDSPF   FILE(IGCLIB/IGCDSP)  IGCDTA(*YES)

This command changes the display device file IGCDSP, which is stored in the library IGCLIB, so that it processes double-byte character set data.