Create DDM File (CRTDDMF)

Where allowed to run: All environments (*ALL) Threadsafe: No

Parameters Examples Error messages

The Create Distributed Data Management File (CRTDDMF) command creates a distributed data management (DDM) file.

A DDM file is used as a reference file to access a file located on a remote (target) system in the distributed data management network. The DDM file on the local system contains the name of the remote file and information identifying the remote system. It also specifies the method used to access the records in the remote file.

Top

---

 

Parameters

Keyword	Description	Choices	Notes
FILE	DDM file	Qualified object name	Required, Positional 1
	Qualifier 1: DDM file	Name
	Qualifier 2: Library	Name, *CURLIB
RMTFILE	Remote file	Element list	Required, Positional 2
	Element 1: File	Single values: *NONSTD Other values: Qualified object name
	Qualifier 1: File	Name
	Qualifier 2: Library	Name, *LIBL, *CURLIB
	Element 2: Nonstandard file 'name'	Character value
RMTLOCNAME	Remote location	Single values: *RDB Other values: Element list	Required, Positional 3
	Element 1: Name or address	Character value
	Element 2: Type	*SNA, *IP
RDB	Relational database	Name	Optional
TEXT	Text 'description'	Character value, *BLANK	Optional
DEV	Device	Element list	Optional
	Element 1: APPC device description	Name, *LOC
LCLLOCNAME	Local location	Communications name, *LOC, *NETATR	Optional
MODE	Mode	Communications name, *NETATR	Optional
RMTNETID	Remote network identifier	Communications name, *LOC, *NETATR, *NONE	Optional
PORT	Port number	1-65535, *DRDA	Optional
ACCMTH	Access method	Single values: *RMTFILE, *COMBINED Other values: Element list	Optional
	Element 1: Remote file attribute	*KEYED, *ARRIVAL
	Element 2: Local access method	*BOTH, *RANDOM, *SEQUENTIAL
SHARE	Share open data path	*NO, *YES	Optional
PTCCNV	Protected conversation	*NO, *YES	Optional
LVLCHK	Record format level check	*RMTFILE, *NO	Optional
AUT	Authority	Name, *LIBCRTAUT, *ALL, *CHANGE, *EXCLUDE, *USE	Optional
REPLACE	Replace file	*YES, *NO	Optional

Top

 

DDM file (FILE)

Specifies the DDM file to be created.

This is a required parameter.

Qualifier 1: DDM file

name

Specify the name of the DDM file to be created.

Qualifier 2: Library

*CURLIB

The current library for the job is used to locate the DDM file. If no current library is specified as the current library for the job, QGPL is used.

name

Specify the name of the library where the DDM file is located.

Top

 

Remote file (RMTFILE)

Specifies the name of the remote file as it is coded on the target system. This file name must be specified in code page 500. The remote file does not need to exist when the Distributed Data Management (DDM) file is created.

This is a required parameter.

Element 1: File

Single values

*NONSTD

The remote file name is not at standard iSeries file name. Specify the complete file name in apostrophes for the second element of this parameter.

Qualifier 1: File

name

Specify the name of the remote file as it is known on the remote system. If the remote system is an iSeries system, specify the file name. The file name can be up to 10 characters in length. If the remote system is a System/36, the file name is the same as its System/36 file label. The file name can be up to eight characters in length. If the remote system is a System/38, a simple (unqualified) file name can be specified. The file name can be up to 10 characters in length. Labels for all other remote systems (including qualified file names for System/38) must use *NONSTD followed by the remote file name in apostrophes.

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.

The library name is used only if the target system is an iSeries system. If *CURLIB is specified, the current library in the called job on the target system is searched to locate the file. If *LIBL is specified, the library list in the called job on the target system is searched to locate the file.

Element 2: Nonstandard file 'name'

character-value

For target systems that allow naming conventions other than those used by the iSeries system and System/36, and when specifying a qualified System/38 file name and when specifying a member name of a remote iSeries or System/38 file, specify up to 255 characters for the name of the remote file to be accessed. The name must be coded in the form required by the target system. The name must always be enclosed in apostrophes, and may contain lowercase letters, blanks, periods, or any other special characters.

Names for the iSeries system, System/38, and System/36 must be in uppercase, and no blanks are allowed.

If the target system is an iSeries system or a 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 must follow the value *NONSTD, and the member name must be enclosed in parentheses and immediately follow (with no space) either the library name (System/38) or the file name (iSeries).

Top

 

Remote location (RMTLOCNAME)

Specifies the remote (target) system location name or address used with the distributed data management (DDM) file. The remote location name or address does not have to be defined before the DDM file is created, but it must be defined before the DDM file is opened. Multiple DDM files can use the same remote location for the target system.

This is a required parameter.

Single values

*RDB

The remote location information from the relational database entry specified for the Relational database (RDB) parameter is used to determine the remote system.

Element 1: Name or address

character-value

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 remote location 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 address type 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 address type 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 address type 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 address type of this parameter must be specified as *IP.

If *IP is specified for the address type, 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 specified, the DDM server must support SNA connectivity, and the PORT parameter will be ignored.

Element 2: Type

*SNA

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

*IP

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

More information on remote locations is in the APPC Programming book, SC41-5443.

Top

 

Relational database (RDB)

Specifies the relational database entry that is used to determine the remote location information for the DDM file.

name

Specify the name of the relational database entry that identifies the target system or target auxiliary storage pool (ASP) group. The relational database name can refer to a remote system or an ASP group that is configured and available on a remote system. The relational database entry does not need to exist when the DDM file is created but must exist when the DDM file is opened. This parameter is required when *RDB is specified for the Remote location (RMTLOCNAME) parameter.

Top

 

Text 'description' (TEXT)

Specifies the text that briefly describes the object.

*BLANK

No text is specified.

character-value

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

Top

 

Device (DEV)

Specifies the name of the source system communications device that is used with this distributed data management (DDM) file.

This parameter will be ignored if *IP is specified for the Remote location (RMTLOCNAME) parameter.

*LOC

The communications device associated with the remote location is used. If several devices can be associated with the remote location, the system determines which device is used.

name

Specify the name of a communications device that is associated with the remote location. If the device name is not valid for the remote location, an escape message is sent when the DDM file is opened.

Top

 

Local location (LCLLOCNAME)

Specifies the local location name.

This parameter will be ignored if *IP is specified for the Remote location (RMTLOCNAME) parameter.

*LOC

The local location name specified for the remote location is used.

*NETATR

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

communications-name

Specifies the name of the local location used with the remote location name. The local location name is only specified to indicate a specific local location for the remote location.

More information on local location names is in the APPC Programming book, SC41-5443.

Top

 

Mode (MODE)

Specifies the mode name that is used with the remote location name to communicate with the remote (target) system.

This parameter will be ignored if *IP is specified for the Remote location (RMTLOCNAME) parameter.

*NETATR

The mode in the network attributes is used.

BLANK

A mode name consisting of 8 blank characters is used.

communications-name

Specify the name of the mode.

More information on mode names is in the APPC Programming book, SC41-5443.

Top

 

Remote network identifier (RMTNETID)

Specifies the identifier (ID) of the remote network in which the remote location resides. That ID is used to communicate with the remote (target) system.

If this parameter is specified, the Remote location (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 for the RMTLOCNAME parameter.

*LOC

The remote network ID specified for the remote location is used.

*NETATR

The remote network identifier specified in the network attributes is used.

*NONE

No remote network ID is used.

communications-name

Specify the remote network ID that is used with the remote location name. The remote network ID is specified only to indicate a specific remote network ID for the remote location.

More information on remote network IDs is in the APPC Programming book, SC41-5443.

Top

 

Port number (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 *SNA is specified for the Remote location (RMTLOCNAME) parameter.

*DRDA

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

1-65535

Specify the port number to be used.

Top

 

Access method (ACCMTH)

Specifies the DDM access method used to open the remote file and access its records. This parameter is ignored if the remote (target) system is a System/38 or an iSeries system.

*RMTFILE

The source system selects the access method that is compatible with both the specified remote file and the access methods supported for that file by the remote (target) system. For systems other than the iSeries system 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 both the combined by key (*KEYED *BOTH) and the combined by record number (*ARRIVAL *BOTH) access methods. 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.

Element 1: Remote file attribute

*KEYED

Remote file is a keyed file.

*ARRIVAL

Remote file is a non-keyed file.

Element 2: Local access method

*BOTH

Remote file allows both sequential and random record access.

*RANDOM

Remote file allows random record access.

*SEQUENTIAL

Remote file allows sequential record access.

Determining the Access Method

The two elements of this parameter indicate the access method to be used to access the remote file. The following table shows the combinations of 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 program intends to access the records in the remote file.

Figure: Access Method Combinations of Values

Remote Local Access Method File Attributes *SEQUENTIAL *RANDOM *BOTH ---------- ------------ ------------ ------------ *ARRIVAL Relative by Random by Combined by record number record number record number *KEYED Relative by Random by Combined by key key 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.

Top

 

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.

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

Top

 

Protected conversation (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 information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter. PTCCNV(*NO) must be specified if *IP is specified for the Remote location (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.

Top

 

Record format level check (LVLCHK)

Specifies whether the level identifiers of the record formats in the remote file are checked when the DDM file is opened by a program. 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 system and not a System/38, the source iSeries system 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.

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

Top

 

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.

On the target system, the authority needed to access the remote file is also checked by using the user profile of the started job on the target system.

*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. Users included on the authorization list are granted authority to the object as specified by the list. The authorization list must exist when the object is created.

Top

 

Replace file (REPLACE)

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

*YES

An existing file is replaced if the creation of a new DDM file with the same name and library is successful.

*NO

The creation of a new DDM file is not allowed if there is an existing file with the same name and library.

Top

---

 

Examples

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

Top

---

 

Error messages

*ESCAPE Messages

CPF7302

File &1 not created in library &2.

Top