Add Logical File Member (ADDLFM)

The Add Logical File Member (ADDLFM) command adds a named file member to a logical file which must already exist on the system. The maximum number of members that can be added to the file is specified for the Maximum members (MAXMBRS) parameter on the Create Logical File (CRTLF) command or the Change Logical File (CHGLF) command. To add other members to the file, use the ADDLFM command to specify each one.

A logical file member can use the data from all, or a subset of, the physical files referenced by the logical file. Each member has its own set of data and can have its own access path that provides an organization to that data. The system attempts to implicitly share an access path already on the system.

Each added member has the same attributes as those defined in the logical file.

Restrictions:

To add a member to a keyed logical file, you must have object operational (*OBJOPR) authority and either object management (*OBJMGT) or object alter (*OBJALTER) authority for each of the physical files on which the logical file member is based (specified explicitly by the DTAMBRS parameter or implicitly by the PFILE or JFILE keyword specified in DDS).
For a member added to a non-keyed logical file, *OBJOPR authority for each of the physical files is required.
This command is conditionally threadsafe. In multithreaded jobs, this command is not threadsafe for distributed files and fails for distributed files that use relational databases of type *SNA. This command is also not threadsafe and fails for Distributed Data Management (DDM) files of type *SNA, when SYSTEM(*RMT) or SYSTEM(*FILETYPE) is specified.

Note: An *EXCLRD lock is required on the file to add a member. Because this command adds a member to a file in a library, the library must not be locked (*SHRNUP or *EXCLRD with the Allocate Object (ALCOBJ) command) in another job.

Parameters

Keyword	Description	Choices	Notes
FILE	Logical file	Qualified object name	Required, Positional 1
	Qualifier 1: Logical file	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
MBR	Logical file member	Name	Required, Positional 2
DTAMBRS	Physical file data members	Single values: ALL Other values (up to 32 repetitions): Element list*	Optional
	Element 1: Physical file	Qualified object name
	Qualifier 1: Physical file	Name
	Qualifier 2: Library	Name, *CURRENT
	Element 2: Member	Single values: NONE Other values (up to 32 repetitions): Name*
TEXT	Text 'description'	Character value, *BLANK	Optional
SHARE	Share open data path	NO, YES	Optional

Top

Logical file (FILE)

Specifies the logical file to which the member is to be added.

This is a required parameter.

Qualifier 1: Logical file

name: Specify the name of the logical file.

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 is used to locate the logical file. If no library is specified as the current library for the job, QGPL is used.
name: Specify the library where the logical file is located.

Logical file member (MBR)

Specifies the logical file member to be added. The member name must be unique in the file.

If the FILE parameter specifies a DDM file and a member name is specified as part of the remote file name in the DDM file, the member names must be the same.

This is a required parameter.

name: Specify the name of the logical file member to be added.

Physical file data members (DTAMBRS)

Specifies the physical files and members that contain the data associated with the logical file member being added by this command. A logical file member can be based on all (*ALL) of the physical files and members on which the logical file itself is based, or the member can be based on a subset of the total files and members.

Note: When adding a member to a logical file that is a DDM file, the physical file, if specified, must also be a DDM file with its library and member(s) specified explicitly. *CURRENT is not supported when the logical file is a DDM file.

When a logical file is created, the physical files specified for the PFILE or JFILE DDS keyword are used to create the logical file. If no library name is specified for the physical files on the PFILE or JFILE keyword, the library list (*LIBL) at file creation time is used to find the physical files; the physical files from the library list are used to create the logical file. The qualified physical files from the PFILE or JFILE keyword (regardless of whether a library name was specified or if the library list was used to find the files) are the physical files associated with the logical file. The names of the physical files associated with the logical file are saved in the description of the logical file. When a member is added to the logical file, the DTAMBRS parameter is used to specify the physical file members associated with the logical file member. Each physical file name specified on the DTAMBRS parameter must be the name of a physical file that is associated with the logical file (saved in the description of the logical file).

Single values

*ALL: The logical file member being added is based on all the physical files and members (that exist at the time this CRTLF command is entered) used by the logical file. At least one member must exist in at least one of the physical files. The physical file names are specified for the PFILE or JFILE parameter in the DDS.

Element 1: Physical file

Qualifier 1: Physical file

name: Specify the names of the physical files that contain the data being accessed by the logical file member being added.
The physical file names must match a name on the PFILE or JFILE keywords in the DDS and cannot be specified more often on the DTAMBRS parameter than on the PFILE or JFILE keywords in the DDS. For join logical files, all physical files specified for the JFILE keyword must be specified for the DTAMBRS parameter and each physical file must contain only one member. If a physical file name is not specified for a physical file that is on a PFILE or JFILE keyword in the DDS, the logical file member is not based on any member of that physical file.

Qualifier 2: Library

*CURRENT: 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.
If a library name is not specified, the current library name (*CURRENT) from the logical file description is used. If the library name is specified, the physical file must be a physical file associated with the logical file. If the logical file is associated with more than one physical file of the same name, the library name must be specified.
name: Specify the name of the library to be searched.

Element 2: Member

Single values

*NONE: A member name is not specified.

Other values (up to 32 repetitions)

name

Specify the names of the physical file members that contain the data being accessed by the logical file member being added.

When the FILE parameter specifies a join logical file or an arrival sequence logical file, only one data member must be specified for the DTAMBRS parameter for each physical file that was specified for the PFILE or JFILE keyword in the DDS. *ALL is valid only if each based-on physical file has only one member. If any of the physical files has more than one member, the specific physical file member must be specified for the DTAMBRS parameter.

The same physical file name can be specified more than once on the JFILE keyword. In this case, each occurrence of the file name is treated as a different based-on physical file, and must be specified for the DTAMBRS parameter.

Up to 32 qualified physical file names and physical file member names can be specified. Also, the total number of member names cannot exceed 32. For example, one file can specify 32 members, two files can each have 16 members, or 32 files can each have one member specified.

For DDM file:

The file names specified in the DTAMBRS parameter must be the names of the DDM files that represent the remote based-on physical files. If a member name was specified as part of the remote file name in the DDM file, only that member name can be specified for the DTAMBRS parameter. The member names must be the actual remote file member names.
The based-on physical files must be at the same system location as the logical file to which the member is being added.
When no member name is specified for the remote file name in the DDM file, all members are accessible. When only one member name is specified, only that member is accessible through that DDM file.

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.

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.

Examples

ADDLFM   FILE(INVENLIB/STOCKTXS)  MBR(JANUARY)
         DTAMBRS((INVENTXS (JANUARY)))
         TEXT('JANUARY STOCK ACTIVITY BY LOCATION')

This command adds a member named JANUARY to the logical file named STOCKTXS in the INVENLIB library. The logical file has access to the data stored in the JANUARY member of the INVENTXS physical file.

Error messages

*ESCAPE Messages

CPF3204: Cannot find object needed for file &1 in &2.
CPF7306: Member &1 not added to file &2 in &3.