FILE

Describe a file to be read

FILE file.structure [ID id] [PARENT pid] [SEPARATE] 
[RELATION name] | [[LINK_FIELD link_field] [LINK_NAME link_name] 
[TO_KEY to_key] [LINK_SEGMENT segment ...]]

Arguments

file.structure

The name of a file and associated structure to be read from in a report.

ID id

(optional) The identification number of this file.structure within a report. Each file.structure must contain a unique ID to enable secondary files to identify their parent’s file.structure. After a file.structure (primary or secondary) is selected for reading while running ReportWriter, a new list of related file.structures is available. All secondary file.structures must come from these lists.

PARENT pid

(optional) The identification number of this file.structure’s parent. It must have been previously defined. The first file.structure is assumed to be the primary file, and any parent ID specified is ignored.

SEPARATE

(optional) Indicates that this file.structure and all of its siblings (other file.structures that have been chosen from the same parent’s list) should be used individually to create detailed records first from the first file.structure, then second from the second file.structure, and so on for the rest of the siblings. This flag must be set for the last sibling.

RELATION name

(optional) The name of the relation between this file.structure and its parent. The name is a two‑digit alphanumeric field that is obtained from the repository. This argument is not required if only one relation exists between this file.structure and its parent.

LINK_FIELD link_field

(optional) The field in the parent file.structure that has the same name link as the first segment of this file.structure.

LINK_NAME link_name

(optional) The name link that is used to build a name linked relation. Indicates that this file.structure is selected from its parent file.structure name link field.

TO_KEY to_key

(optional) The name of the access key in the file you’re defining to which a name link relation has been established with the parent.

LINK_SEGMENT segment

(optional) Indicates that this name link relation can use a user‑modified key. Nonlink base segments can be modified. Specify the key segment that could be a field name or a literal value. You can list more than one segment (separated by spaces) for such a link relation. (A name link may require more than one segment to establish a relation.) If no LINK_SEGMENT argument follows a LINK_NAME argument, RDL will use the default name link method to build a link key. See Determining the list of available secondary files based on name links for information about the default name link method.

Discussion

The FILE statement describes a file with an associated structure from which ReportWriter will read when a report is processed. The maximum number of files to read in a report is 49.

The files determine which structures can be read from when a report is being processed. The order of files in the report schema determines the order in which they are processed by ReportWriter. The first file listed is assumed to be the primary file.

You can specify either a relation (with the RELATION keyword) or a name link relation (with the LINK_FIELD, LINK_NAME, TO_KEY, and LINK_SEGMENT keywords). You cannot specify both.

Examples

In the example below, CUSTOMER.CUST_TAG is the primary file.structure (ID = 1), and CUSTOMER.CUSTOMER, ORDER.ORDER, and PRODUCT.PRODUCT are secondary file.structures. Since there is more than one relation between ORDER.ORDER and its parent (CUSTOMER.CUSTOMER), the relation name (3) must be specified.

FILE CUSTOMER.CUST_TAG ID 1 
FILE CUSTOMER.CUSTOMER ID 2 PARENT 1
FILE ORDER.ORDER       ID 3 PARENT 2 RELATION 3
FILE PRODUCT.PRODUCT   ID 4 PARENT 3

The example contains four levels of file.structures, as shown below.

However, if the parent of PRODUCT.PRODUCT were CUSTOMER.CUSTOMER, there would be only three levels, and PRODUCT.PRODUCT and ORDER.ORDER would be sibling file.structures, as illustrated below.