CHGDDMF (Change Distributed Data Management File)

CHGDDMF Command syntax diagram

 

Purpose

The Change Distributed Data Management File (CHGDDMF) command changes, in the distributed data management file (DDM) description, one or more of the attributes of the specified DDM file. The DDM file is used as a reference file by programs on the iSeries 400 to access files located on any target system in the iSeries 400 DDM network.

 

Required Parameters

FILE
Specifies the qualified name of the DDM file being changed.

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

DDM-file-name: Specify the name of the DDM file that is changed.

 

Optional Parameters

RMTFILE
Specifies the name of the remote file coded in the form required by the target system. This file name must be specified in code page 500. The file does not need to exist when the DDM file is created or changed.

*SAME: The value does not change.

Element 1: Remote File Name

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

Note: The library name is used only if the target system is an iSeries 400.

remote-file-name: Specify up to 10 characters for an iSeries 400 file name, up to 10 characters for a System/38 simple file name, or up to 8 characters for a System/36 file name, to identify the remote file accessed. No apostrophes, blanks, or any other special characters are allowed, and any lowercase characters are always changed to uppercase.

  • If the target system is an iSeries 400:

    • If *LIBL (the default library qualifier) is specified or assumed, the library list in the evoked job on the target system is used to search for the file.

    • If *CURLIB is specified, the current library in the evoked job on the target system is searched for the file.

    • A member name can be specified as part of the remote file name, but it is considered a nonstandard name and the library, file, and member name parts must follow the value *NONSTD.


  • If the target system is a System/38:

    • A qualified file name can be specified as part of the remote file name, but it is considered a nonstandard name and the full file name must follow the value *NONSTD.

    • A qualified file name and member name can be specified as part of the remote file name but is considered a nonstandard name and the full file name must follow the value *NONSTD.

    • If *LIBL is specifies as the library value, the library list in the called job on the target system is searched to locate the file.


  • If the target system is a System/36, the remote file name is the same as its System/36 file label, as used by System/36 OCL.

For examples of standard remote file names, refer to the description of this parameter in the Create Distributed Data Management File (CRTDDMF) command description.

*NONSTD: For target systems that allow naming conventions other than those used by an iSeries 400 and System/36, and when specifying a qualified System/38 file name, and when specifying a member name of a remote iSeries 400 or System/38 file, enter the value *NONSTD and specify the non-standard file name for element 2.

Element 2: Non-standard File Name

If *NONSTD was specified for element 1, specify up to 255 characters for the name of the remote file accessed. The name must be in the form required by the target system. The name must always be enclosed in apostrophes, and can contain lowercase letters, blanks, periods, or other special characters. The iSeries 400 and System/38 name must be in uppercase (because they are not changed to uppercase if enclosed in apostrophes) and no blanks are allowed.

If the target system is an iSeries 400 or System/38, a file name, library name, and member name can be specified. If a member name is specified, the full file name must be enclosed in apostrophes and follow the value *NONSTD, and the member name (with no space) either the library name or the file name.

must be enclosed in parentheses and immediately follow For examples of specifying nonstandard remote file names and member names, refer to the description of this parameter in the CRTDDMF command description.

RMTLOCNAME
Specifies the name or address of the remote location that is used with this object.

Note: Several DDM files can use the same remote location for the target system.

*SAME: The value does not change.

*DEVD: The remote location name associated with the APPC device description is used.

Note: If DEV(*LOC) is specified for the APPC device description, a remote location name must be specified for RMTLOCNAME.

Element 1: Name or Address

remote-location-name: Specify the name or address of the remote location that is associated with the target system. The remote location, which is used in accessing the target system, does not need to exist when the DDM file is created or changed, but must exist when the DDM file is opened. The first element of this parameter can take several forms:

  • SNA remote location name (LU name). Specify a maximum of 8 characters for the remote location name. If this form is used, the second element of this parameter must be *SNA (the default).

  • SNA remote network identifier and remote location name separated by a period. Specify a maximum of 8 characters for the remote location name, and a maximum of 8 characters for the remote network identifier. If this form of the parameter is used, the second element of this parameter must be *SNA (the default), and any value specified for the RMTNETID parameter must agree.

  • IP address in dotted decimal form. Specify an internet protocol address in the form nnn.nnn.nnn.nnn where each nnn is a number in the range 0 through 255. If this form is used, the second element of this parameter must be specified as *IP.

  • IP host domain name. Specify an internet host domain name of up to 254 characters in length. If this form is used, the second element of this parameter must be specified as *IP.

If *IP is specified for the second element, the DDM server at the remote location must support the use of TCP/IP, and the DEV, LCLLOCNAME, RMTNETID, and MODE parameters will be ignored.

If *IP is not specifed, the DDM server must support SNA connectivity, and the PORT parameter will be ignored.

Element 2: Address Type

*SAME: The value does not change.

*SNA: The remote location has a Systems Network Architecture (SNA) address type.

*IP: The remote location has an Internet Protocol (IP) address type.

DEV
Specifies the name of the APPC device description on the source system that is used with this DDM file. The device description does not need to exist when the DDM file is created or changed. This parameter will be ignored if *IP is specified in the RMTLOCNAME parameter.

More information on device names is in APPC, APPN, and HPR topic in the Information Center.

*SAME: The value does not change.

*LOC: The device associated with the remote location is used. If several devices are associated with the remote location, the system determines which device is used.

Note: If RMTLOCNAME(*DEVD) is specified for the remote location, a device name must be specified for DEV.

device-name: Specify the name of a communications device associated with the remote location. If the device name is not valid for the remote location, a message is sent when the program device entry is acquired. More information on device names is in APPC, APPN, and HPR topic in the Information Center.

LCLLOCNAME
Specifies the local location name. This parameter will be ignored if *IP is specified in the RMTLOCNAME parameter.

*SAME: The value does not change.

*LOC: The local location name associated with the remote location is used.

*NETATR: The LCLLOCNAME value specified in the system network attributes is used.

local-location-name: Specify the name of the local location that is associated with the remote location. The local location name is specified only if the user wants to indicate a specific local location for the remote location. If the local location name is not valid for the remote location, an escape message is sent when the DDM file is opened.

MODE
Specifies the mode name that is used with the remote location name to communicate with the target system. This parameter will be ignored if *IP is specified in the RMTLOCNAME parameter.

More information on mode names is in APPC, APPN, and HPR topic in the Information Center.

*SAME: The value does not change.

*NETATR: The mode name specified in the network attributes is used.

mode-name: Specify the name of the mode that is used. If the mode name is not valid for any combination of remote location and local location, an escape message is sent when the DDM file is opened.

RMTNETID
Specifies the remote network ID in which the remote location resides and is used to communicate with the target system. If this parameter is specified, the RMTLOCNAME parameter must be consistent with this RMTNETID parameter. If the RMTLOCNAME parameter specified a network ID, this parameter must agree (otherwise, an error message will be issued). If the RMTLOCNAME parameter does not specify any network ID, there is no possibility of conflict with this parameter. This parameter will be ignored if *IP is specified in the RMTLOCNAME parameter.

More information on remote network IDs is in APPC, APPN, and HPR topic in the Information Center.

*SAME: The value does not change.

*LOC: The remote network identifier (ID) associated with the remote location is used. If several remote network IDs are associated with the remote location, the system determines which remote network ID is used.

*NETATR: The RMTNETID value specified in the system network attributes is used.

*NONE: No remote network identifier (ID) is used.

remote-network-ID: Specify the remote network ID that is associated with the remote location. The remote network ID is specified only if the user indicates a specific remote network ID for the remote location. If the remote network ID is not valid for the remote location, an escape message is sent when the DDM file is opened.

PORT
Specifies the TCP/IP port that is used at the remote location to communicate with the system on which the remote file is located. This parameter will be ignored if *IP is not specified in the RMTLOCNAME parameter.

*SAME: The port identification does not change.

: The DRDA well-known port of 446 will be used. This the port on which the iSeries 400 DDM TCP/IP server listens.

port-number: Specify a number in the range 1-65535.

ACCMTH
Specifies, when the remote file is on a non-iSeries 400 and non-System/38 target system, the DDM access method used to open the remote file and access its records. Specifying a value other than *RMTFILE for this parameter may improve performance when processing requests to remote files on non-iSeries 400 and non-System/38 targets.

This parameter is ignored when the target system is an iSeries 400 or a System/38; a remote iSeries 400 or System/38 file is accessed as if it were a local file.

*SAME: The value does not change.

*RMTFILE: The source system selects the access method that is compatible with (a) the attributes of the remote file identified by the RMTFILE parameter and (b) the access methods used by the target system for that file. If this value is used for non-iSeries 400 and non-System/38 target systems, and the source system cannot select an access method when the file is opened, a message is sent to the program user. A different value should be specified for this parameter after the target system operator has been contacted about the appropriate access method information for the file.

*COMBINED: The DDM combined access method is used for the remote file. This access method combines the file processing capabilities of the combined by key (*KEYED *BOTH) and the combined by record number (*ARRIVAL *BOTH) access methods, as shown in the following table. The record can be selected with a key value or a record number. From that position, the position can be set relatively or randomly by key value or by record number. If duplicate keys are present in the file, they are processed in the order defined by each target system's implementation of the DDM architecture.

access-method: Specify a set of two values that indicates the access method that is used to access the remote file. If only the first value is specified (*ARRIVAL or *KEYED), the default for the second value is *BOTH, and either random or relative (sequential) selection can be requested.

The following table shows the other possible values for the ACCMTH parameter. The remote file attributes (in the far left column) refer to the type of file on the target system. The local access method (in the last three columns) refers to the way in which the source iSeries 400 or System/38 program intends to access the records in the remote file.

Table 1. Access Method (ACCMTH) Other Values

Remote
File
Attributes		 Local Access Method
*SEQUENTIAL *RANDOM *BOTH
*ARRIVAL Relative by record number Random by record number Combined by record number
*KEYED Relative by key Random by key Combined by key

Relative by record number access method (*ARRIVAL *SEQUENTIAL): This method allows access to records relative to the current position in record number sequence. The record number is not specified to identify the record.

Random by record number access method (*ARRIVAL *RANDOM): This method allows access to records by specifying a record number in a random sequence determined by the requester.

Combined by record number access method (*ARRIVAL *BOTH): This method combines the capabilities of the relative by record number and random by record number access methods.

Relative by key access method (*KEYED *SEQUENTIAL): This method allows records in a keyed file accessed in key value sequence. Records can be accessed by moving forward or backwards in key sequence from the current record. The key value is not specified to identify the record.

Random by key access method (*KEYED *RANDOM): This method allows records in a keyed file accessed in a random sequence. Records are selected by their key value and not their position in the file.

Combined by key access method (*KEYED *BOTH): This method combines the capabilities of the relative by key and random by key access methods.

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

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

Operation considerations (regarding buffers and file position, for example) for SHARE(*YES) are the same as for database files. When an ODP is shared, the programs accessing the file share things, such as the file status and the buffer.

PTCCNV
Specifies whether the DDM conversation that is started for the DDM file is a protected conversation or not. A protected conversation is a conversation that uses two-phase commit protocols to ensure, even if a failure occurs, updates made on the remote system are synchronized with updates to other remote or local resources. A protected conversation is required to use two-phase commitment control with DDM. More information on using two-phase commitment control with DDM is in the Distributed Data Management topic in the Information Center. PTCCNV(*NO) must be specified if *IP is specified in the RMTLOCNAME parameter.

*SAME: The value does not change.

*NO: The DDM conversation started, using this DDM file, is not a protected conversation.

*YES: The DDM conversation started, using this DDM file, is a protected conversation. Two-phase commitment control can be used with this DDM file.

LVLCHK
Specifies whether the record format level identifiers in the program are checked against those in the remote file when the DDM file is opened. If so, the record format identifiers in the program must match those in the remote file. If they do not match, an error message is sent to the requesting program and neither the DDM file nor the associated remote file is opened. Files that have an error while being opened are automatically closed. This parameter can be overridden by an Override with Database File (OVRDBF) command before the remote file is opened.

*SAME: The value does not change.

*RMTFILE: The level identifiers of the record formats of the remote file (identified in the RMTFILE parameter) are checked at the time the DDM file is opened.

If the target system is not an iSeries 400 or System/38, then the source iSeries 400 creates a level check value based on the record length of the remote file and any key fields used in it. The values are then compared to the values in the program, and they must match before the remote file can be opened. This reduces the possibility that a program will select the wrong file.

Note: Before this can be done for a system other than an iSeries 400 or System/38, the program must be compiled (or recompiled) using the DDM file. During the compilation, the DDM file is used to establish communications with the target system, get the remote file's attributes from the target system, and create the level identifier values so they can be included in the compiled program for later level checking.

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

TEXT
Specifies the text that briefly describes the DDM 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.

Examples for CHGDDMF

The following examples describe the changing of a DDM file.

Example 1: Changing the communications mode System 

CHGDDMF  FILE(SOURCE/SALES)  MODE(MODEX)

This command changes the communications mode for the DDM file named SALES stored in the SOURCE library on the source system. The mode is changed to MODEX.

Example 2: Changing a DDM File to Access a File through TCP/IP 

CHGDDMF   FILE(OTHER/SALES)
  RMTLOCNAME(ROCHESTER.XYZ.COM *IP) PORT(*DRDA)

This command changes the remote location name for the DDM file named SALES stored in the OTHER library on the source system. The remote location is changed to the TCP/IP host having the domain name of ROCHESTER.XYZ.COM. The host listens on the standard DRDA port of 446.

Example 3: Changing a DDM File to Access a File through TCP/IP using dotted decimal IP address and a numeric port number 

CHGDDMF   FILE(OTHER/SALES)
  RMTLOCNAME('9.5.36.17' *IP) PORT(5021)

This command changes the remote location name for the DDM file named SALES stored in the OTHER library on the source system. The remote location is changed to the TCP/IP host with the IP address of 9.5.36.17. The host listens on port 5021.

Error messages for CHGDDMF

*ESCAPE Messages

CPF7304
File &1 in &2 not changed.