CRTDDMF

CRTDDMF (Create Distributed Data Management File)

CRTDDMF Command syntax diagram

Purpose

The Create Distributed Data Management File (CRTDDMF) command creates a distributed data management (DDM) file. The DDM file is used as a reference file by programs to access files located on a remote (target) system in the DDM network. Programs on the local (source) system know a remote file only by the DDM file's name, not by the remote file's actual name. (The DDM file name, however, can be the same as the remote file name.)
The DDM file (on the source system) contains the name of the remote file accessed and the name or address of the remote (target) system that contains the file. It can also specify the type of access method that is used to access records in the remote file.

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

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

DDM-file-name: Specify the name of the DDM file being created.

RMTFILE

Specifies the name of the remote file on 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.
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, that identifies the remote file accessed. No apostrophes, blanks, or any other special characters are allowed, and any lowercase characters are 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 called job on the target system is searched to locate the file.

If *CURLIB is specified, the current library in the called job on the target system is searched to locate 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 (member) name parts must follow the value *NONSTD.

If the target system is a System/38 system:

A qualified file 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.

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

*NONSTD: For target systems that allow naming conventions other than those used by iSeries 400, System/38, and System/36, and when specifying a member name of a remote iSeries 400 or qualified name or member name of a remote 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 names 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 a System/38, a file and library name can be specified enclosed in apostrophes following the value *NONSTD.
If the target system is an iSeries 400 or System/38, a file name, library name, and member name can all 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 must be enclosed in parentheses and immediately follow (with no space) either the library name or the file name.

If the target system is an iSeries 400 or System/38 and *LIBL is specified, the library list in the evoked job on the target system is used to search for the file.

If the target system is an iSeries 400 and *CURLIB is specified, the current library in the evoked job on the target system is used to search for the file.

Examples of specifying iSeries 400 remote file member names are:
RMTFILE(*NONSTD 'CAR(JULY)') RMTFILE(*NONSTD 'SALES/CAR(JULY)')

Examples of specifying System/38 remote file member names are:
RMTFILE(*NONSTD 'CAR.SALES') RMTFILE(*NONSTD 'CAR.*LIBL') RMTFILE(*NONSTD 'CAR(JULY)') RMTFILE(*NONSTD 'CAR.SALES(JULY)')

RMTLOCNAME

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

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

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 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. If the RMTNETID parameter is not specified, the RMTNETID value will be set to agree with the RMTLOCNAME parameter.

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
*SNA: The remote location has a Systems Network Architecture (SNA) address type.
*IP: The remote location has an Internet Protocol (IP) address type.

Optional Parameters

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. This parameter will be ignored if *IP is specified in the RMTLOCNAME parameter.
*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.
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.

LCLLOCNAME

Specifies the local location name. This parameter will be ignored if *IP is specified in the RMTLOCNAME parameter.
*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.
*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 indicates 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.
*NETATR: The mode name specified in the network attributes is used.
*BLANK: Text is not specified.
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 that 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.
*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.
*DRDA: 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 not on an iSeries 400 or 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 also improve performance when processing requests to remote files on a system other than an iSeries 400 or System/38 targets.
This parameter is ignored when the target system is an iSeries 400 or a System/38; the access to a remote iSeries 400 and System/38 file is supported as if it were a local file.
*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 supported by the target system for that file. For systems other than the iSeries 400 and System/38 target systems, if this value is used 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 must then be specified for this parameter, using the CHGDDMF command, after someone at the target system 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. The position can then 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
*KEYED or *ARRIVAL: 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 (*KEYED or *ARRIVAL), the default for the second value is *BOTH, and either random or relative (sequential) selection can be requested.
The other possible values for the ACCMTH parameter are shown below. 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.

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

The following explanations refer to the possible values for the ACCMTH parameter.
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 to be 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 to be 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 DDM 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.

Operation considerations (regarding buffers and file position, for example) for SHARE(*YES) are the same as for database files.

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.
*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.
*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 and not a System/38, 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 created values are then compared to the values in the program, and they must match before the remote file can be opened. This reduces the chances of the wrong file being selected.

Note: Before this can be done for a system other than an iSeries 400 or a 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 generate 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.

AUT

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

REPLACE

Specifies whether an existing file is replaced by the new DDM file. More information on this parameter is in Commonly used parameters.
*YES: An existing file is replaced by the DDM file being created.
*NO: No replacement occurs.

TEXT

Specifies the text that briefly describes the DDM file. More information on this parameter is in Commonly used parameters.
*BLANK: Text is not specified.
'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Examples for CRTDDMF
The following examples describe the creation of a DDM file.
Example 1: Creating a DDM File to Access a File at Another iSeries 400
CRTDDMF FILE(SOURCE/SALES) RMTFILE(REMOTE/SALES) RMTLOCNAME(NEWYORK)

This command creates a DDM file named SALES, and stores it in the SOURCE library on the source system. This DDM file uses the remote location named NEWYORK to access a remote file named SALES stored in the REMOTE library on an iSeries 400 in New York.
Example 2: Creating a DDM File to Access a File Member at Another IBM iSeries 400
CRTDDMF FILE(SOURCE/SALES) RMTLOCNAME(NEWYORK) RMTFILE(*NONSTD 'REMOTE/SALES(APRIL)')

This command creates the same file as in the previous example, except that now it accesses a specific member in the remote SALES file; the member is named APRIL.
Example 3: Creating a DDM File to Access a File on a System/38
CRTDDMF FILE(OTHER/SALES) RMTLOCNAME(CHICAGO) RMTFILE(*NONSTD 'PAYROLL.REMOTE')

This command creates a DDM file named SALES, and stores it in the library OTHER on the source system. The remote location CHICAGO is used by the DDM file to access a remote file named PAYROLL in library REMOTE on a System/38.
Example 4: Creating a DDM File to Access a File on a System/36
CRTDDMF FILE(OTHER/SALES) RMTFILE(PAYROLL) RMTLOCNAME(DENVER) LVLCHK(*NO)

This command creates a DDM file named SALES, and stores it in the library OTHER on the source system. The remote location DENVER is used by the DDM file to access a remote file named PAYROLL on a System/36 in Denver. No level checking is performed between the PAYROLL file and the application programs that access it. Because the ACCMTH parameter was not specified, the access method for the target system is selected by the source iSeries 400 when the DDM file is opened to access the remote file.
Example 5: Creating a DDM File to Access a File through TCP/IP
CRTDDMF FILE(OTHER/SALES) RMTFILE(PAYROLL) RMTLOCNAME(ROCHESTER.XYZ.COM *IP) PORT(*DRDA)

This command creates a DDM file named SALES, and stores it in the library OTHER on the source system. The remote location ROCHESTER.XYZ.COM is used by the DDM file to access a remote file named PAYROLL on a TCP/IP host with the domain name of ROCHESTER.XYZ.COM. The host listens on the standard DRDA port of 446. (Since *DRDA is the default port, the PORT parameter is not actually neccessary in this case.)
Example 6: Creating a DDM File to Access a File through TCP/IP using dotted decimal IP address and a numeric port number
CRTDDMF FILE(OTHER/SALES) RMTFILE(PAYROLL) RMTLOCNAME('9.5.36.17' *IP) PORT(5021)

This command creates a DDM file named SALES, and stores it in the library OTHER on the source system. The remote location 9.5.36.17 is used by the DDM file to access a remote file named PAYROLL on a TCP/IP host with an IP address of 9.5.36.17. The host listens on port 5021.
Error messages for CRTDDMF
*ESCAPE Messages

CPF7302

File &1 not created in library &2.

Remote File Attributes	Local Access Method
Remote File Attributes	*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