CRTSRCPF (Create Source Physical File)

CRTSRCPF Command syntax diagram

 

Purpose

The Create Source Physical File (CRTSRCPF) command creates a source physical file in the database. A source physical file is created from the file description parameters in the CRTSRCPF command; it is used to store source records that are used as input to IBM-supplied source processors, such as the data description specifications (DDS) processor, CL compiler, or RPG III compiler. To override attributes of the file after it has been created, use the Override Database File (OVRDBF) command before the file is opened. To change attributes of the file after it has been created, use the Change Source Physical File (CHGSRCPF) command.

Restrictions

1. This command is not threadsafe for DDM files of type *SNA, when SYSTEM(*RMT) or SYSTEM(*FILETYPE) is specified.

 

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

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

source-physical-file-name: Specify the name of the source physical file being created.

Note:

If a DDM file is specified, the source physical file (specified in the RMTFILE parameter of the CRTDDMF command) is created on a remote system (specified in the RMTLOCNAME parameter of the CRTDDMF command). See the SYSTEM parameter of this command.

 

Optional Parameters

RCDLEN

Specifies the length (in bytes) of the records being stored in the source file. The format of each record contains three fields: the sequence number of the record, a date field, and the source statement. The record format name is the same as the file itself, specified in the FILE parameter. More information on this parameter is in Commonly used parameters.

The RCDLEN parameter must provide six positions for the source sequence number, six positions for the date field, and at least one position for source start. If the Copy File (CPYF) command is used to copy records into the file, and the records are longer than the length specified, the records are truncated on the right. These fields are defined with fixed attributes and names, and have a keyed access path over the sequence number if ACCPTH(*KEYED) is specified.

92: The default record length is 92 characters. Six characters are for the record sequence number, 6 are for the record date, and the remaining 80 characters are for the source statement.

record-length: Specify the record length of each source record in the file. Valid values range from 13 through 32766.

Double-Byte Character Set Considerations:

If IGCDTA(*YES) is specified, the RCDLEN parameter must provide six positions for the source sequence number, six positions for the date field, and at least four positions for source start. Valid values range from 16 through 32766.

MBR

Specifies the name of the source file member being added when the source file is created. Other members can be added to the file after it is created by using the ADDPFM command.

*NONE: No member is added when the file is created.

*FILE: The member being added has the same name as that of the source file that contains the member (specified in the FILE parameter).

source-file-member-name: Specify the name of the member that is added when the source file is created.

SYSTEM

Specifies the system on which the source physical file is created.

*LCL: The source physical file is created on the local system.

*RMT: The source physical file is created on a remote system that is using DDM. The file name specified on the FILE parameter must be the name of a DDM file (created by using the CRTDDMF command). The DDM file contains the name of the source physical file being created (RMTFILE parameter on the CRTDDMF command) on the remote system (RMTLOCNAME parameter on the CRTDDMF command).

*FILETYPE: If the name specified on the FILE parameter is a DDM file, the physical file is created on the remote system specified by the RMTLOCNAME parameter on the CRTDDMF command for that DDM file. Otherwise, the name on the FILE parameter cannot be the name of an existing file, since a physical file of that name is created on the local system.

EXPDATE

Specifies the expiration date. The files cannot be overwritten until the expiration date. The expiration date must be later than or equal to the current date.

Note:

Attempting to open a member for which the expiration date has been exceeded sends an error message to the user.

*NONE: No expiration date is specified.

expiration-date: Specify the date after which the source file member cannot be used. The date must be in the format specified by the QDATFMT and QDATSEP job attributes. The date must be enclosed in apostrophes if special characters are used in the format.

MAXMBRS

Specifies the maximum number of members that the source file being created can contain at any one time.

*NOMAX: The system maximum is used.

maximum-members: Specify the maximum number of members that the source file can contain. Valid values range from 1 through 32767 members per file.

ACCPTH

Specifies the type of access path used by all members of the file.

*ARRIVAL: The access path governs the arrival sequence order. Using this parameter value reduces the size of the file and avoids maintenance of the keyed access path.

*KEYED: The access path is of keyed sequence order.

More information on keyed access paths and the arrival sequence orders of source file access paths is in the Database Programming topic in the Information Center.

ACCPTHSIZ

Specifies the maximum size of auxiliary storage that can be occupied by access paths that are associated with keyed source physical files. This parameter does not apply to access paths that are created for logical files or for queries that refer to the data in a source physical file.

*MAX1TB: The access paths associated with this file can occupy a maximum of one terabyte (1,099,511,627,776 bytes) of auxiliary storage.

Note:

This value is not supported on releases of the system earlier than Version 3 Release 6 Modification 0 (V3R6M0). Therefore, if an attempt is made to save a physical file that has this attribute, and the save operation specifies a target release earlier than V3R6M0, the save operation might be unsuccessful, or if successful, the access paths are not saved. If the save operation is successful and the saved version of the file is then used to restore the physical file, the system rebuilds all of the access paths.

*MAX4GB: The access paths associated with this file can occupy a maximum of four gigabytes (4,294,966,272 bytes) of auxiliary storage. This value provides compatibility with releases of the operating system earlier than Version 3 Release 6 Modification 0.

MAINT

Specifies the type of access path maintenance used for all members of the source file that have keyed access paths.

*IMMED: The access path is maintained for each physical file member whether the source physical file is opened or closed. The access path is changed whenever a record is updated, added to, or deleted from a member of this file or a logical file member based on a member of this file.

*REBLD: The access path is completely rebuilt when a file member is opened during program running. The access path is continuously maintained until the member is closed, then the access path maintenance ends.

*DLY: The maintenance of the access path is delayed until the physical file member is opened for use. 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 its members are immediately reflected in the access path of those members, no matter what is specified for the MAINT parameter. To prevent a lengthy rebuild time when the file is opened, *DLY should be specified only when the number of changes to the access path is small.

If the number of changes between a close and the next open 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.

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 has occurred while the access path is being changed. This parameter is valid only for files with a keyed access path.

If *IMMED is specified for the MAINT parameter, the access path can be rebuilt during initial program load (IPL) (before any user can run a job), after IPL has ended (when jobs are running at the same time), or when the file is reopened. 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 access paths that must be recovered and what the RECOVER parameter value is for each. The RECOVER parameter values on this display can be overridden. More information on this is in the Backup and recovery topic in the Information Center.

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

*NO: The access path of the file is not rebuilt during *IPL or *AFTIPL. The file's access path, if not valid, is rebuilt when the file is reopened.

*AFTIPL: The file has its access path rebuilt after the IPL has been completed. This option allows other jobs not using this file to start processing immediately after the IPL has been completed. If a job tries to allocate the file while its access path is being rebuilt, a file- open exception occurs.

*IPL: The file has its access path rebuilt during the IPL. 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.

FRCACCPTH

Specifies, for files with keyed access paths only, whether access path changes are forced to auxiliary storage along with the associated records in the file whenever the access path is changed. FRCACCPTH(*YES) minimizes (but does not remove) the possibility that an abnormal job end can cause damage to the access path, which requires it to be rebuilt.

*NO: The access path and updated records are not forced to auxiliary storage whenever the access path is changed.

*YES: The access path and updated records are forced to auxiliary storage whenever the access path is changed. If FRCACCPTH(*YES) is specified, MAINT(*REBLD) cannot be specified.

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 somewhat decreased.

SIZE

Specifies the initial number of records in each member of the file, the number of records in each increment that can be automatically added to the member size, and the number of times the increment is automatically applied. The number of records for each file member is specified as the number of records that can be placed in it. This includes deleted records.

When the maximum number of records has been reached, a message, stating that the member is full is sent to the system operator, offering the choice of ending the request or extending the member size. The operator can extend the member by 10% or by the number of records specified as the increment value, whichever is greater, each time the message is received.

A list of 3 values can be specified to indicate the initial size of each member and the automatic extensions that can be added when needed, or *NOMAX can be specified. If SIZE is not specified, SIZE(10000 1000 499) is assumed by the system.

Element 1: Number of Records

One of the following is used to specify the initial number of records in the member before an automatic extension of the member occurs. The ALLOCATE parameter determines when the required space for the initial number of records is allocated. If *YES is specified, the space is allocated when a new member is added. If *NO is specified, the initial space is allocated as determined by the system.

10000: Initially, up to 10,000 records can be inserted into each member of the file before an extension occurs.

number-of-records: Specify the number of records (ranging from 1 through 16777215) that can be inserted before an automatic extension occurs. If automatic extensions are not wanted, enter zeros for the second and third values in the list.

Element 2: Increment Value

One of the following is used to specify the number of records that can be additionally inserted in the member when the initial member size is exceeded and an automatic extension occurs. The minimum size of an increment is 10% of the size of the member at the time the maximum number of records is reached.

1000: The member size is increased by 10% or 1,000 records, whichever is greater.

increment-value: Specify the number of additional records (ranging from 0 through 32767) which, if greater than 10% of the size of the member when the maximum number of records is reached, are to be added to the member during an automatic extension.

If the number specified is not greater than 10% of the member size and not equal to zero, the member size is increased by 10%.

Specify 0 to prevent automatic extensions. This value must be 0 if the value for the number of increments is 0.

Element 3: Maximum Number of Increments

One of the following values is used to specify the maximum number of increments that can be automatically added to a file member. If 0 is specified for the increment amount, the number of increments need not be specified; 0 will be the default value instead of 499 and a file-member-full message is sent to the user issuing the command.

499: Up to 499 increments can be automatically added to the member size.

number-of-increments: Specify the maximum number of increments, ranging from 0 through 32767, that can be automatically added to the member. To prevent automatic extensions, specify a value of 0.

Other Single Values

If SIZE(*NOMAX) is specified, ALLOCATE(*NO) must also be specified.

*NOMAX: The system maximum is used.

ALLOCATE

Specifies whether storage space is allocated for the initial number of records (SIZE parameter) for each source file member as it is added. The allocation provides enough space to hold the initial number of records specified by the SIZE parameter. Later allocations, which occur when a record cannot be added to a member without exceeding its capacity, are determined by the system and by the SIZE parameter values.

*NO: Minimum storage space is initially allocated when the member is added. The system determines when space allocations are necessary and determines the size of each allocation.

*YES: Storage space is initially allocated as each member is added. The amount specified in the first value of the SIZE parameter (the number of records) is allocated. If the space cannot be allocated, a message is sent to the user and the affected member is not added. If ALLOCATE(*YES) is specified, SIZE(*NOMAX) cannot be specified.

CONTIG

Specifies whether records in the initial allocation in each source file member are stored contiguously (next to each other) on auxiliary storage. If so, and the necessary contiguous space is not available, the system sends a message to the job log and allocates the storage space separately. The file is still usable. This parameter does not affect additional allocations needed later, which most likely would be noncontiguous.

*NO: The storage space for each member does not have to be together.

*YES: The system allocates contiguous space for the added members of the source file. If the members are stored separately, the user is notified and a message is put in the job log. If CONTIG(*YES) is specified, ALLOCATE(*YES) must also be specified.

UNIT

This parameter is no longer supported. It exists solely for compatibility with releases earlier than Version 3 Release 6 Modification 0 of the AS/400 system. For information on using auxiliary storage pools (ASPs), refer to the Backup and recovery topic in the Information Center.

You can specify the value *ANY or a value ranging from 1 through 255 on this parameter. Specifies whether a file is stored on a specific auxiliary storage unit. The system attempts to allocate the storage space for the file and for all of its members and their associated access paths on the specified unit. This includes the initial allocation when each member is added and any extensions that occur later for each member in the file. If the system cannot allocate the storage space for each member on the specified unit, it allocates the space on any available unit and sends a message to the job log. The file is entirely usable in all cases.

The unit identifier is a number ranging from 1 through 255 that is assigned when a new disk device is configured. The user can display and change the configured disk device using the Work with Disk Devices display from the Start System Service Tool (STRSST) command. More information on the System Service Tool (SST) is in the Backup and recovery topic in the Information Center.

*ANY: The storage space for the file and its members is allocated on any available auxiliary storage unit.

unit-identifier: Specify the storage unit where the system attempts to allocate storage space for the file and all of its members.

If the unit specified is part of any user auxiliary storage pool (auxiliary storage pools ranging from 2 through 16), the system allocates space from ASP 1, the system auxiliary storage pool.

FRCRATIO

Specifies the number of inserted, updated, or deleted records processed before being forced to auxiliary (permanent) storage. More information on this parameter is in Commonly used parameters.

If this physical file is being journaled, a larger force ratio should be specified. More information on journal management is in the Journal management article in the Information Center.

*NONE: There is no forced write ratio; the system determines when the records are written to auxiliary storage.

number-of-records-before-force: Specify the number of inserted, updated, or deleted records processed before they are explicitly forced to auxiliary storage.

IGCDTA

Specifies whether the file contains double-byte character set (DBCS) data.

*NO: The file does not process DBCS data.

*YES: The file processes DBCS data.

WAITFILE

Specifies the number of seconds that the program waits for the file resources and session resources to be allocated when the file is opened, or for the device or session resources to be allocated when an acquire operation is performed to the file. If those resources are not allocated within the specified wait time, an error message is sent to the program. More information on this parameter is in Commonly used parameters.

Note:

An immediate allocation of the device by the device resource is required when an acquire operation is performed to the file.

*IMMED: The program does not wait; when the file is opened, an immediate allocation of the file resources is required.

*CLS: The job default wait time is used as the wait time for the file resources being allocated.

number-of-seconds: Specify the number of seconds a program waits for the file resources to be allocated to the job. Valid values range from 1 through 32767 seconds.

WAITRCD

Specifies the number of seconds that a program waits for a record to be updated or deleted, or for a record read in the commitment control environment with LCKLVL(*ALL) specified. More information on record locking is in the Database Programming topic in the Information Center. If the record is not allocated in the specified wait time, an error message is sent to the program.

60: A program waits 60 seconds for a requested record.

*IMMED: The program does not wait; when a record is locked, an immediate allocation of the record is required.

*NOMAX: The system maximum is used.

number-of-seconds: Specify the number of seconds that a program waits for a record requested for reading, updating, or deleting. Valid values range from 1 through 32767 seconds.

CCSID

Specifies the coded character set identifier (CCSID) being used to describe character data in the fields of the source file.

A CCSID is a 16-bit number identifying a specific set of encoding scheme identifiers, character set identifiers, code page identifiers, and additional coding-related information that uniquely identifies the coded graphic representation used.

*JOB: The current job's default CCSID is used.

*HEX: The CCSID 66535 is used, which indicates that the character data in the fields is treated as bit data and is not converted.

coded-character-set-identifier: Specify the CCSID being used. More information on valid CCSIDs is in the Globalization topic in Information Center.

SHARE

Specifies whether the open data path (ODP) for the source physical 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, provided the scope specified on the OPNSCOPE keyword for the subsequent open of the file is compatible with the scope of the original open.

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.

DLTPCT

Specifies the maximum percentage of deleted records allowed in any member in the source file. The percentage is based on the number of deleted records compared with the total record count in a member. The percentage check is made when any member of the file is closed or any logical file member based on any member of the file is closed. If the number of deleted records exceeds the percentage, a message is sent to the system history log (QHST) to inform the user.

*NONE: No percentage is specified; the number of deleted records in the file members is not checked when a member is closed.

deleted-records-threshold-percentage: Specify, from 1 through 100, the largest percentage of deleted records allowed in any member in the file. If this percentage is exceeded, a message is sent to the system history log (QHST) when the file is closed.

ALWUPD

Specifies whether records are updated in the physical file. Records in a logical file can be updated only when the records in each physical file on which the logical file is based can be updated.

*YES: Records can be updated in the physical file.

*NO: Records cannot be updated in this physical file or in any logical file built over this physical file.

ALWDLT

Specifies whether records can be deleted from the physical file. Records in a logical file can be deleted only when the records in each physical file on which the logical file is based can be deleted.

*YES: Records can be deleted in this physical file.

*NO: Records cannot be deleted in this physical file or from any logical file built over this physical file.

AUT

Specifies the authority given to users who do not have specific authority to the source physical file, who are not on an authorization list, and whose user group has no specific authority to the source physical file. More information on this parameter is in Commonly used parameters.

*LIBCRTAUT: The public authority for the source physical file is taken from the value on the CRTAUT parameter of the target library (the library that is to contain the source physical file). The public authority is determined when the source physical file is created. If the CRTAUT value for the library changes after the source physical file is created, the new value does not affect any existing objects.

*CHANGE: The user can perform all operations on the source physical 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 source physical 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 source physical file.

*USE: The user can perform basic operations on the source physical file, such as running a program or reading a file. The user cannot change the source physical file. *USE authority provides object operational authority, read authority, and execute authority.

*EXCLUDE: The user cannot access the source physical file.

authorization-list-name: Specify the name of the authorization list used.

TEXT

Specifies the text that briefly describes the source physical 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 CRTSRCPF

Example 1: Creating a File Without Members

CRTSRCPF   FILE(SRCLIB/PAYTXS)

This command creates a source file named PAYTXS in the SRCLIB library. The file is created without any members; therefore, no data can be put into the file until a member is added later. As many as 32,767 members (*NOMAX) can be added to the file.

Each member can have up to 10000 records before automatic extensions (499 increments maximum) occur that add 1000 records to the capacity of the member. Only minimum initial storage is allocated for each member with no restrictions on whether the space is connected. The public has object operational, read, add, delete, and update authority for the file, but no object management or object existence authority.

Example 2: Creating a File With a Member

CRTSRCPF   FILE(ORDERCTL/ORDERS)  MBR(*FILE)
  SIZE(100 50 5)

This command creates a source physical file named ORDERS in the ORDERCTL library. Storage space for the records placed in the file need not be contiguous. The initial allocation of storage provides for up to 100 records, and up to five increments of additional space for 50 records each can be added automatically. These allocation values also apply to members of this source file that will be added later.

Example 3: Creating a File that Contains DBCS Data

CRTSRCPF   FILE(IGCLIB/IGCSRC)  IGCDTA(*YES)

This command creates a source physical file named IGCSRC, which is stored in the library IGCLIB, and can contain DBCS data.

Error messages for CRTSRCPF

*ESCAPE Messages

CPF323C

QRECOVERY library could not be allocated.

CPF5702

File either not DDM file or not found.

CPF7302

File &1 not created in library &2.