When you create a report, the first file you select is the primary file. All other files that you select are secondary files. This topic describes how ReportWriter determines the list of available primary and secondary files. It also describes how ReportWriter determines the list of secondary files based on name links stored in the repository cross-reference file.
ReportWriter does not include files that are flagged as temporary. See Defining files for information about flagging file definitions as temporary.
Determining the list of available primary files
ReportWriter reads the repository and then lists all files that have one or more structures assigned to them. Each such file is listed once in the Available Files list. If the file you select has more than one structure assigned to it, the Available Structures list is then displayed. From this list you can select the appropriate structure. For example, if both
Structure : CMCLNT Description : Customer client
and
Structure : MSCLNT Description : Master client
are assigned to the CLIENT file, these two entries appear in the Available Structures list:
Customer client
Master client
Determining the list of available secondary files
Once a primary file is selected, you can display the list of available secondary files. Secondary files are related to the primary file, either directly or indirectly.
ReportWriter reads the repository to find all relations that are defined for the current structure. For example, using the items listed above, if you select
CLIENT.Master client
as your primary file, ReportWriter will look up all relations defined for structure MSCLNT. If the relations defined for MSCLNT are as follows:
|
From key |
To structure |
To key |
|---|---|---|
|
CLNTID |
ARCUST |
CUSTID |
|
CONTID |
CMCONT |
CONTID |
ReportWriter will look up all files assigned to all “to” structures. These files will comprise the list of available secondary files. (These files are directly related to the primary file.) If ARCUST is assigned to the files AR92 (Accounts receivable 92) and AR93 (Accounts receivable 93), and CMCONT is assigned to the file CONTCT (Contact), the list of available files will be as follows:
Accounts receivable 92
Accounts receivable 93
Contact
Each file is listed once in the Available Files list. If the file you select has more than one structure assigned to it, the Available Structures list is then displayed. From this list you can select the appropriate structure.
Additionally, if the selected structure is used in more than one relation between it and the structure of the primary file, a third list — the Available Relations list — is displayed. This list displays the “from key” and “to keys” involved in the relations. From this list you can select the appropriate relationship between the primary and secondary file.
Once a secondary file has been selected, you can display the list of files related to it or redisplay those related to the primary file. Files linked to the secondary file are considered to be indirectly related to the primary file.
The primary file can also appear as a secondary file; this will happen if one of the secondary files defines a relation back to the primary file.
Determining the list of available secondary files based on name links
Once a primary file is selected, you can display the list of secondary files that are available through name links, rather than those based on predefined relations. ReportWriter creates a foreign “from” key and a temporary relation in order to access these secondary files.
Name links are established in Repository and allow “name linked” fields to be used to access related data. Each field (and template) in the repository has a “name link” flag. This flag determines whether the field name itself should be used to find matches or if an alternate name link should be used. The alternate name link is the name of the field’s template or the name of the template’s parent if the name link flag is set.
The list of possible name link relations for a given repository exists in the repository cross-reference file, which is generated by the Repository Generate cross-reference utility. Each record in this file links a field with an access key in another structure.
When you select Add file via name link, ReportWriter reads the cross-reference file in order to display a list of fields in the current file that have name links to other files. These fields are displayed in the Link Fields from filename list.
When you select one of the link fields, ReportWriter reads the cross-reference file to find all access keys in all structures to which this field has a name link. ReportWriter then looks up all files assigned to these structures. These files will comprise the list of available secondary files.
Each file is listed once in the Available Files list. If the file you select has more than one name linked structure assigned to it, the Available Structures list is displayed. From this list you can select the appropriate structure.
Additionally, if more than one record was found in the cross-reference file linking the link field with the selected structure, a fourth list — the Available Relations list — is displayed. This list displays the “link field” and the “to” key (the access key) involved in each possible relation. From this list you can select the relationship that ReportWriter should construct between the primary and secondary file.
Constructing temporary relations
When you select a secondary file (based on a name link) ReportWriter constructs both a foreign key (the “from” key) and a temporary relation, linking this “from” key to the selected “to” key. Depending on the link field selected and the “to” key used, the following situations are possible:
- If the link field is the first and only segment of the “to” key, ReportWriter constructs a single-segment, nonmodifiable foreign key. (Note that the link field name and the “to” key field name will not necessarily be the same. The reason the link is possible is that both fields have the same name link.)
- If the link field is the second segment of the “to” key and the first segment is the tag field, ReportWriter creates a two-segment, nonmodifiable foreign key of which the first segment is a literal (the tag comparison value) and the second segment is the link field. The tag must be defined as a Field type tag and must use the EQ (equal) connector.
- If the link field is the first segment of the “to” key and is followed by other segments, ReportWriter constructs a foreign key that matches as many segments as possible, based on name links. If any segments in the “to” key do not have corresponding name-link matching fields in the “from” structure, you must enter literal values for the remaining segments or clear the segments so that ReportWriter does a partial match.
Using external key segments
Repository allows for a special kind of relationship between files, called an external relation. An external relation involves three or more files, where one file is accessed by a key composed of segments from the remaining files. For example, the item type from one file (file A), along with the item number from a second file (file B), can be used to access the item ID in a third file (file C).
When you create a report, the list of available files will contain all three files. You will want to select file A first. After you select file A, the list of available files will only include file B. File C will not be displayed, because it requires file B. Once you select file B, file C will be displayed, and you can select it.
Similar logic applies when you try to delete files from the report. If you’ve selected all three files, you cannot delete file B until file C has been deleted.
Using non-indexed files
ReportWriter currently supports two non-indexed file types: ASCII and relative. Since ReportWriter does random access on all secondary files, ASCII files can be used only as primary files. Relative files can be used as both primary and secondary files.
In order for ReportWriter to access relative files properly, an access key must be defined for those files in Repository. A relative file can have only one access key: the record number. For convenience, when you create a structure whose file type is relative, Repository automatically creates an access key with the proper attributes. The key is named RECORD_NUMBER, and it has an ascending sort order, allows no duplicates, and has one segment of type R (record number). In addition to the access key created for you, you can also define foreign keys for a relative file.
When using a relative file as your primary file, you have two methods of accessing other files:
- If you use the RECORD_NUMBER access key as the “from” key in the relation, as ReportWriter processes sequentially through the file, the current record’s position will be used as the key value for accessing the related file.
- You can also use a foreign key. When sequentially processing the file, the current record is used to construct the foreign key, and its value is used as the key for accessing the related file.
Because a secondary file (the “to” part of a relation) can be accessed only via access keys, the only method of accessing a relative secondary file is via the record number. The key value is constructed from the primary file (whether it be a field, an external key, a literal, or a relative file’s record number), and it is then used as the number of the record to read from the secondary file.
