CHGDSPF (Change Display File) Command Description

CHGDSPF Command syntax diagram

Purpose

The Change Display File (CHGDSPF) command changes, in the file description, one or more of the attributes of the specified display device file.

Required Parameter

FILE

Specifies the qualified name of the display device file whose description is being changed.

Depending on the library qualifier specified or assumed, the following libraries, for which the user has the authority, are searched for the specified objects:

The name of the display device 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.

*USRLIBL: Only the libraries in the user portion of the job's library list are searched.

*ALL: All libraries in the system, including QSYS, 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    #DFULIB    #RPGLIB    #SEULIB
#COBLIB    #DSULIB    #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        QPFRDATA     QUSRBRM      QUSRSYS
QGPL         QRCL         QUSRIJS      QUSRVxRxMx
QGPL38       QS36F        QUSRINFSKR
QMQMDATA     QUSER38      QUSRNOTES
QMQMPROC     QUSRADSM     QUSRPYMSVR

Note:

A different library name, of the form QUSRVxRxMx, can be created by the user for each release that IBM supports. VxRxMx is the version, release, and modification level of the library.

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

*ALL: All the display device files in the specified library are changed.

file-name: Specify the file name that is to be changed.

generic*-file-name: Specify the generic name of the file. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. If the complete object name is specified, and multiple libraries are searched, multiple objects can be changed only if *ALL or *ALLUSR library values can be specified for the name. See generic names for additional information.

Optional Parameters

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.

*SAME: The value does not change.

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

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

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.

*SAME: The value does not change.

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.

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.

*SAME: The value does not change.

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

TEXT

Specifies the text that briefly describes the display device file. More information is in commonly used parameters.

*SAME: The value does not change.

*BLANK: Text is not specified.

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

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: The 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.

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.

*SAME: The value does not change.

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

*SAME: The value does not change.

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

*SAME: The value does not change.

*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 attribute to determine whether to use the *JOBCCSID or *DEVD special value on the CHRID command parameter for this file.

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

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.

*SAME: The value does not change.

*FILE: Use the decimal format value stored with the file when the file was created.

*JOB: Use the decimal format value from the DECFMT job attribute when the file is opened.

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

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.

*SAME: The value does not change.

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

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.

The possible values for program-described files are:

*SAME: The value does not change.

*NO: The file does not process DBCS data.

*YES: The file processes DBCS data.

The possible values for externally described files are:

*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 putting the DDS keyword IGCALTTYP into effect and identifying DBCS attributes of fields or messages in the DDS.

IGCEXNCHR

Specifies whether the system processes double-byte character set (DBCS) extension characters.

*SAME: The value does not change.

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

*SAME: The value does not change.

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

*SAME: The value does not change.

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

*SAME: The value does not change.

*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 DB2 UDB for AS/400 Database Programming book.

*SAME: The value does not change.

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

Examples for CHGDSPF

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.

Error messages for CHGDSPF

*ESCAPE Messages

CPF7304

File &1 in &2 not changed.

CPF7308

&5 files not changed for &1 in &2. &4 files changed.