Create Logical File (CRTLF)

The Create Logical File (CRTLF) command creates a logical file from the information specified on this command and from the data description specifications (DDS) contained in a source file.

A logical file is a database file that describes how data records contained in one or more physical files are presented to a program. The logical file does not contain data records. The data records are contained in the physical files associated with the logical file.

The data records contained in the physical files are grouped into physical file members. The logical file accesses the data records through one or more logical file members. Each logical file member describes the data contained in one or more physical file members, and each logical file member has its own access path to the data. Normally, database files have only one member which, by default, is added to the file when the file is created.

Restrictions:

• To create a keyed logical file over one or more physical files, you must have object operational (*OBJOPR) authority and either object management (*OBJMGT) authority or object alter (*OBJALTER) authority for each of the files specified for the PFILE or JFILE keywords in DDS.

  To create a non-keyed logical file, only *OBJOPR authority 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.

Parameters

File (FILE)

Specifies the logical file to be created.

If the file is used in a high-level language program, the file name should be consistent with the naming rules of that language; otherwise, the file must be renamed in the program.

This is a required parameter.

Qualifier 1: File

name

Specify the name of the logical file.

Qualifier 2: Library

*CURLIB

The file is located in the current library for the job. If no library is specified as the current library for the job, QGPL is used.

name

Specify the library where the file is located.

Note: If a logical file and the physical file on which it is based are in different libraries, and the logical or physical file does not exist when it is to be restored (such as during disaster recovery or when the files are deleted), the access path is not restored. It is rebuilt. To make it possible for access paths to be restored and not rebuilt, the logical files and the based-on physical files must be in the same library. More information on the restoring of saved access paths is in the Recovering your system book, SC41-5304.

Source file (SRCFILE)

Specifies the source file that contains the data description specifications (DDS) source used to create the logical file.

Qualifier 1: Source file

QDDSSRC

The DDS source file QDDSSRC contains the source descriptions used to create the logical file.

name

Specify the name of the source file that contains the DDS used to create 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 for the job is used to locate the source file. If no library is specified as the current library for the job, QGPL is used.

name

Specify the library where the source file is located.

Source member (SRCMBR)

Specifies the name of the source file member that contains the DDS source for the logical file being created.

*FILE

The source file member name is the same as the name specified for the File (FILE) parameter.

name

Specify the name of the member in the source file.

Generation severity level (GENLVL)

Specifies the severity level of data description specifications (DDS) messages that cause file creation to fail. This parameter applies only to messages created while processing DDS source files.

20

If errors occur in the DDS source file processing with a severity level greater than or equal to 20, the file is not created.

0-30

Specify the desired severity level value. If 0 is specified, the file is not created. The value specified must be greater than or equal to the value specified for the Flagging severity level (FLAG) parameter.

Flagging severity level (FLAG)

Specifies the minimum severity level of messages to be listed.

0

All messages are listed.

0-30

Specify a number indicating the minimum severity of messages to be listed. The value specified must be greater than or equal to the value specified for the Generation severity level (GENLVL) parameter.

File type (FILETYPE)

Specifies whether each member of the logical file being created contains data records, or contains source records for a program or another file.

*DATA

The logical file contains data records.

*SRC

The logical file contains source records. This value cannot be specified for join logical files.

Logical file member (MBR)

Specifies the logical file member to be added when the logical file is created.

*FILE

The name of the member to be added is the same as the name specified for the File (FILE) parameter.

*NONE

No member is added when the file is created.

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.

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.

*SRCMBRTXT

If the source file is a database file, the text is taken from the source file member used to create the file. If the source file is an inline file or a device file, the text is blank.

*BLANK

No text is specified.

character-value

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

Source listing options (OPTION)

Specifies the type of output produced when the file is created. A maximum of four of the following values can be specified in any order on this parameter. If neither or both of the values on an option are specified, the first value listed for the option is used.

Note: The first values on each option are similar to, but are not actually default values, and therefore, cannot be changed with the CHGCMDDFT (Change Command Default) command.

Source Listing Option

*SRC or *SOURCE

A printout of the source statements, including a list of errors, is created.

*NOSRC or *NOSOURCE

No printout of the source statements is created unless errors are detected. If errors are detected, they are listed along with the keyword or record format that caused the error.

Program Listing Option

*LIST

An expanded source printout is created, showing a detailed list of the file specifications and the references to other file descriptions.

*NOLIST

The expanded source printout is not created.

Second-Level Message Text Option

*NOSECLVL

The messages section of the data description specifications (DDS) printout does not contain the online help information for messages issued during DDS processing.

*SECLVL

The online help information appears in the DDS printout.

Event File Creation Option

*NOEVENTF

The compiler does not produce an event file for the CoOperative Development Environment (CODE) product.

*EVENTF

The compiler produces an event file that can be used by the CODE product. The event file is created as a member in the file EVFEVENT in your object library. The CODE product uses this file to offer error feedback integrated with the CODE editor. This value is normally specified by the CODE product on your behalf.

System (SYSTEM)

Specifies whether the logical file is created on the local system or the remote system.

*LCL

The logical file is created on the local system.

*RMT

The logical file is created on a remote system. The file specified for the File (FILE) parameter must be the name of a DDM file that identifies the remote system and the name of the logical file being created.

*FILETYPE

If the file specified for the FILE parameter does not exist on the system, the logical file is created on the local system. Otherwise, the file on the FILE parameter must be a DDM file, and the logical file is created on a remote system. The DDM file identifies the remote system and the name of the logical file being created.

Maximum members (MAXMBRS)

Specifies the maximum number of members that the logical file can contain.

1

Only one member can be contained in the file.

*NOMAX

The number of members that can be contained in the file is the system maximum of 32,767 members.

integer

Specify the maximum number of members that can be contained in the file. Valid values range from 1 through 32767.

Access path size (ACCPTHSIZ)

Specifies the maximum size of auxiliary storage that can be occupied by access paths that are associated with join logical files or with files that have keyed sequence access paths.

Note: For a join logical file, this parameter applies to all join secondary access paths even if the join logical file is not a keyed file.

*MAX1TB

The access paths associated with this file can occupy a maximum of 1.7 terabytes of auxiliary storage.

*MAX4GB

The access paths associated with this file can occupy a maximum of four gigabytes (4,294,966,272 bytes) of auxiliary storage.

Access path logical page size (PAGESIZE)

Specifies the access path logical page size that is used when the access path is created.

The access path logical page size is used by the system to determine the size of each page of the index. This logical page size is the amount of bytes of the access path that can be moved into the job's storage pool from the auxiliary storage for a page fault.

*KEYLEN

The access path logical page size will be determined by the total length of the key, or keys.

8

Logical page size of 8k.

16

Logical page size of 16k.

32

Logical page size of 32k.

64

Logical page size of 64k.

128

Logical page size of 128k.

256

Logical page size of 256k.

512

Logical page size of 512k.

Access path maintenance (MAINT)

Specifies, for files with key fields or join logical files, the type of access path maintenance used for all members of the logical file.

*IMMED

The access path is updated each time a record is changed, added, or deleted from a member. *IMMED must be specified for files that require unique keys.

*REBLD

The access path is completely rebuilt each time a file member is opened. The access path is maintained until the member is closed, then the access path is deleted. *REBLD cannot be specified for files that require unique keys.

*DLY

The maintenance of the access path is delayed until the logical file member is opened. Then the access path is changed only for records that have been added, deleted, or changed since the file was last opened. While the file is open, all changes made to based-on file members are immediately reflected in the access paths of the opened file's own members, no matter what is specified for this parameter. To prevent a long rebuilding time when the file is opened, *DLY should be specified only when the number of changes to the access path between successive open operations are small; that is, when the file is opened frequently or when the key fields in records for this access path change infrequently. *DLY is not valid for access paths that require unique key values.

If the number of changes between a close operation and the next open operation reaches approximately 10 percent of the access path size, the system stops saving changes and the access path is completely rebuilt the next time the file is opened. The access path is updated when the member is opened with records that have been added, deleted, or changed from the member since the last time the member was opened.

Access path recovery (RECOVER)

Specifies, for files having immediate or delayed maintenance on their access paths, when recovery processing of the file is performed after a system failure occurs while the access path is being changed. This parameter is valid only for join logical files or files with a keyed access path.

If *IMMED or *DLY is specified for the Access path maintenance (MAINT) parameter, the access path can be rebuilt during initial program load (IPL) (before any user can run a job), after IPL has ended (during concurrent job running), or when the file is next opened. While the access path is being rebuilt, the file cannot be used by any job.

During the IPL, an Override Access Path Recovery display lists those paths that must be recovered and what the RECOVER parameter value is for each path. The user can override the RECOVER parameter value on this display. More information is in the Recovering your system book, SC41-5304.

If *REBLD is specified for the MAINT parameter, the access path is rebuilt the next time its file is opened.

*NO

The access path of the file is rebuilt when the file is opened. *NO is the default for all files that do not require unique keys.

*AFTIPL

The access path of the file is rebuilt after the initial program load (IPL) operation is completed. This option allows other jobs not using this file to start processing immediately after the completion of IPL. If a job tries to allocate the file while its access path is being rebuilt, a file open exception occurs. *AFTIPL is the default for files that require unique keys.

*IPL

The access path of the file is rebuilt during the IPL operation. This ensures that the file's access path is rebuilt before the first user program tries to use it; however, no jobs can start running until after all files that specify RECOVER(*IPL) have their access paths rebuilt.

Force keyed access path (FRCACCPTH)

Specifies, for files with key fields or a join logical file, whether access path changes are forced to auxiliary storage along with the associated records in the file. FRCACCPTH(*YES) minimizes (but does not remove) the possibility that an abnormal job end could cause damage to the access path that would require it to be rebuilt.

Note: For a join logical file, this parameter value applies to all join secondary files even if the join file is not a keyed file.

*NO

The access path and associated records are not written to auxiliary storage whenever the access path is changed.

*YES

The access path and associated records are written to auxiliary storage whenever the access path is changed. *YES cannot be specified if *REBLD is specified for the Access path maintenance (MAINT) parameter.

FRCACCPTH(*YES) slows the response time of the system if the access path is changed in an interactive job. If the access path is changed frequently, the overall performance of the system is affected somewhat.

Preferred storage unit (UNIT)

Specifies the preferred storage media for the file.

*ANY

No storage media is preferred. Storage will be allocated from any available storage media.

*SSD

Solid state disk storage media is preferred. Storage may be allocated from solid state disk storage media, if available.

integer

A value ranging from 1 through 254 is equivalent to specifying *ANY. A value of 255 is equivalent to specifying *SSD.

Rcd format selector program (FMTSLR)

Specifies the record format selector program that is called when the logical file member contains more than one logical record format.

The user-written selector program is called when a record is written to the database file and a record format name is not included in the high-level language program. The selector program receives the record as input, determines the record format used, and returns it to the database.

This parameter is not valid if the logical file has only one record format.

Single values

*NONE

There is no selector program for this logical file.

Qualifier 1: Rcd format selector program

QDDSSRC

The format selector program name is QDDSSRC.

name

Specify the name of the format selector program to be called. A program specified as the format selector program cannot be created with *OWNER specified for the User profile (USRPRF) parameter.

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 program name. If no library is specified as the current library for the job, QGPL is used.

name

Specify the library where the program is located.

Records to force a write (FRCRATIO)

Specifies the number of inserted or updated records that are processed before the records are forced into auxiliary storage.

The force write ratio specified for a logical file cannot be less than or equal to the smallest force write ratio of its based-on files. If a larger force write ratio is specified, it is ignored and a message is sent informing the user of the action.

For example, if the force ratios of three physical files are 2, 6, and 8, the logical file force ratio that is based on these three physical files must be as restrictive as the least of them; that is 2 in this case. Two would be used even if the FRCRATIO parameter is not specified. Thus, each time a program inserts, updates, or deletes two records in the logical file (regardless of which based-on physical files are affected), those records are forced to permanent storage.

If a physical file associated with this logical file is being journaled, a large force write ratio or *NONE is specified. More information on journal management is in the Recovering your system book, SC41-5304.

*NONE

There is no specified force ratio. The system determines when the records are written to auxiliary storage.

integer

Specify the number of inserted or updated records that are processed before the records are written to auxiliary storage.

Maximum file wait time (WAITFILE)

Specifies the number of seconds that the program waits for the file resources to be allocated when the file is opened, or the device or session resources to be allocated when an acquire operation is performed to the file. If the file resources cannot be allocated in the specified wait time, an error message is sent to the program.

30

The program waits for 30 seconds for file resources to be allocated.

*IMMED

The program does not wait. Immediate allocation of file resources is required.

*CLS

The job default wait time is used as the wait time for the file resources to be allocated.

1-32767

Specify the number of seconds to wait for file resources to be allocated.

Maximum record wait time (WAITRCD)

Specifies the number of seconds that the program waits for a record being changed or deleted. If the record cannot be allocated within the specified wait time, an error message is sent to the program.

60

The program waits for 60 seconds for a record being changed or deleted.

*IMMED

The program does not wait. Immediate allocation of file resources is required.

*NOMAX

The wait time is the maximum allowed by the system, which is 32767 seconds.

integer

Specify the number of seconds that the program waits for a record being changed or deleted. Valid values range from 1 through 32767 seconds.

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.

Note: This parameter is not valid when *NONE is specified for the Logical file member (MBR) parameter.

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

Sort sequence (SRTSEQ)

Specifies the sort sequence used for this file. The sort sequence is used with the LANGID parameter to determine which sort sequence table is used.

Single values

*SRC

The table specified in the data description specifications (DDS) on the ALTSEQ keyword is used. If ALTSEQ is not used in the DDS, use the value specified for *JOB on this parameter.

*JOB

The sort sequence value used is the value for the job issuing this command to create the logical file.

*LANGIDSHR

The sort sequence table can contain the same weight for multiple characters, and is the shared weighted table associated with the language specified in the LANGID parameter.

*LANGIDUNQ

The sort sequence table must contain a unique weight for each character in the code page.

*HEX

A sort sequence table is not used, and the hexadecimal values of the characters are used to determine the sort sequence.

Qualifier 1: Sort sequence

name

Specify the name of the sort sequence table.

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 searched. If no library is specified as the current library for the job, the QGPL library is used.

name

Specify the name of the library to be searched.

Language ID (LANGID)

Specifies the language identifier used when *LANGIDSHR or *LANGIDUNQ is specified for the Sort sequence (SRTSEQ) parameter. The language identifier is used with the SRTSEQ parameter to determine which sort sequence table the file uses.

*JOB

The language identifier specified for the job is used.

character-value

Specify a language identifier. To see a complete list of identifiers when prompting this command, position the cursor on the field for this parameter and press F4 (Prompt).

Record format level check (LVLCHK)

Specifies whether the level identifiers of the record formats in the logical file are checked when the file is opened by a program.

*YES

The level identifiers of the record formats are checked. If the level identifiers do not all match, an open error message is sent to the program requesting the open operation.

*NO

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

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.

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

Examples

Example 1: Creating a Logical File Without Members

CRTLF   FILE(INVEN/STOCKCTL)  SRCFILE(SRCLIB/STKLFSRC)
        MBR(*NONE)

This command creates a logical file named STOCKCTL, in the INVEN library. The source descriptions in the source file STKLFSRC in the SRCLIB library are used to create the logical file. The file is created without any members (*NONE was specified), and only one member can be added later (because one member is the default for the MAXMBRS parameters). The logical file accesses the data contained in the physical files specified in the DDS source file used to create this logical file. For successful completion of the CRTLF command, the user must have object operational authority for all the physical files specified in the DDS. If the logical file is keyed, object management authority is also required.

Example 2: Creating a Logical File With Members

CRTLF   FILE(PAYLIB/PAYCODESEQ)  SRCFILE(PAYLIB/PAYTXSRC)
        DTAMBRS(PAYTRANS FIRSTQTR)  AUT(*EXCLUDE)
        TEXT('Pay taxes in code sequence')

This command creates a logical file and logical file member, both named PAYCODESEQ in the PAYLIB library. The file and its member are created from the PAYTXSRC source file that is in the same library. The logical file member accesses the data contained in the FIRSTQTR member of the physical file PAYTRANS. The logical file is secured for the private use of the owner. The owner must have object operational authority for the PAYTRANS file to create the member. If the logical file is keyed, object management authority is also required.

Error messages

*ESCAPE Messages

CPF3204

Cannot find object needed for file &1 in &2.

CPF323C

QRECOVERY library could not be allocated.

CPF5702

File either not DDM file or not found.

CPF7302

File &1 not created in library &2.