The way Agile Business Suite handles an Extract file at runtime is influenced by:
Type of command
Category of Extract file (TEMPORARY, PERMANENT, or EXISTING)
Beginning or end of job processing for the Report
First or subsequent access of the Extract file, or by a particular type of command
The use of extract file built-in methods
A first access is defined as the first execution of a Determine Actual, Sort, Extract, or Match command in the logic of the Report, or following a SetTitle or Restart command.
The following accesses are performed on an Extract file:
Start of Report
Write (Extract Command Execution)
Read (Determine Actual)
Compare (Match Command Execution)
Sort (Sort method)
Name (SetTitle Command Execution)
Restart (Restart Command Execution)
End of Report
The following describes the points listed above in detail. For the purpose of describing how the category of an extract file influences how it is opened and closed implicitly, there is no discussion on extract file built-in methods.
Start of Report
At the beginning of the Report, any Extract files referred to in a RAS command option (RetainAs or RetainedAs) have their category set to PERMANENT and their title set to the last RAS command option in the logic of the Report. All other Extract files have their category set to TEMPORARY.
At the beginning of the Report, any Extract files that are file-equated at runtime have their title set to the title given in the file equate. A file-equated title overrides one that would have been assigned as a consequence of the RAS command. If the RAS command option has been used in logic for the extract file, the category of the file is set to PERMANENT, otherwise it is set to TEMPORARY.
Any SetTitle command has no effect on the Extract file category at the beginning of the Report, since this command only takes effect when it is executed.
No files are actually opened until they are first accessed by the execution of a Determine Actual, Sort Extract or Match command.
A first access is defined as the first execution of a Determine Actual, Sort Extract or Match command in the logic of the Report, or following a SetTitle or Restart command.
Generally speaking, the title set up by a SetTitle command replaces a title that has been set up by the RetainAs command, or assigned by a file-equate, when it is executed. The exception to this rule is in the case where all of the following conditions are met:
The title in the SetTitle command is the same as the one set up by the RetainAs command.
This SetTitle command is executed before the extract file is opened for the first time
In such cases, the title assigned by a file-equate takes precedence and the SetTitle command is ignored. This exceptional behavior is a consequence of the way the RetainAs command has been implemented in AB Suite for systems migrated from EAE. For systems migrated from EAE, the RetainAs command is now a SetTitle command, inserted by migration, at the beginning of logic. To allow file-equates to be used with extract files on which the RetainAs command has been used, this behavior is necessary.
Write (Extract Command Execution)
The Extract command attempts to write a record to the specified Extract File.
If this is the first access of the Extract file, the action performed on the file when the Extract command is executed depends on the category of the file, as shown in the following table.
| State of file | TEMPORARY | PERMANENT | EXISTING |
|---|---|---|---|
| File exists | Cleared | Cleared | Cleared |
| File does not exist | Created | Created | Created |
If this is not the first access of the Extract file, the extracted data is appended to the existing file.
Refer to Extract logic command in the Agile Business Suite Programming Reference Manual and the Extract File Location property in the Agile Business Suite Developer User Guide for more information.
Read and Compare (Determine Actual and Match Command Execution)
The action performed on the specified Extract file when a Determine Actual or Match command is executed depends on whether or not the ExtractedAs command option is included.
With ExtractedAs
The Determine Actual or Match command attempts to read a record from the specified Extract file. The ExtractedAs command option implies that the file was not created by this Report (that is, the Report does not include an Extract command which writes the file and defines the layout).
If this is not the first access of the file, the record is read.
If this is the first access of the file:
If it is a TEMPORARY file, the file is created as an empty file if it does not already exist, or it is cleared if it does exist. The read of the empty file is then immediately set Glb.Status to *****.
If it is a not a TEMPORARY file, the record is read if the file exists, or the Report crashes if the file does not exist.
The following table summarizes the actions performed when this is the first access of the file.
| State of file | TEMPORARY | PERMANENT | EXISTING |
|---|---|---|---|
| File exists | Read | Read | Read |
| File does not exist | Created | Crash | Crash |
Without ExtractedAs
The Determine Actual or Match command attempts to read a record from the specified Extract File. Not including an ExtractedAs command option implies that the file was created by this Report (that is, the Report includes an Extract command that writes the file and defines the layout).
If this is not the first access of the file, the record is read.
If this is the first access of the file:
If it is not an EXISTING file, the file is created as an empty file if it does not already exist, or it is cleared if it does exist. The read of the empty file is then immediately set Glb.Status to *****.
If it is an EXISTING file, the record is read if the file exists, or the Report crashes if the file does not exist.
The following table summarizes the actions performed when this is the first access of the file.
| State of file | TEMPORARY | PERMANENT | EXISTING |
|---|---|---|---|
| File exists | Cleared | Cleared | Read |
| File does not exist | Created | Created | Crash |
Sort (Sort Method)
The Sort method attempts to sort the specified Extract file.
If this is not the first access of the file, the file is sorted.
If this is the first access of the file:
If it is not an EXISTING file, the file is created as an empty file if it does not already exist, or it is cleared if it does exist.
If it is an EXISTING file, the file is sorted if it already exists, or the Report becomes a waiting entry if it does not exist.
The following table shows the actions performed on the Extract file if the Sort method is the first access to it.
| State of file | TEMPORARY | PERMANENT | EXISTING |
|---|---|---|---|
| File exists | Cleared | Cleared | Sorted |
| File does not exist | Created | Created | Wait |
Name (SetTitle Command Execution)
The SetTitle command explicitly closes the specified Extract file and changes the physical name of the file. The file category is changed to PERMANENT if the Exist command option is not included, or to EXISTING if the Exist command option is included. The new file is not opened until it is accessed by a command that reads or writes it.
On entry to the SetTitle command:
If the file previously was a TEMPORARY file, the file is deleted (if it had been created).
If the file previously was a PERMANENT file, the file is created as an empty file (if it does not exist), cleared (if it exists, but has not been accessed), or closed (if it has been accessed).
If the file previously was an EXISTING file, the file is closed (if it has been accessed), otherwise no action is taken.
The following table shows the actions performed on the Extract file on entry to the SetTitle command.
| State of file | TEMPORARY | PERMANENT | EXISTING |
|---|---|---|---|
| File exists | Deleted | Closed/Cleared | No action |
| File does not exist | No action | Created | Closed |
Restart (Restart Command Execution)
The Restart command deletes the specified Extract file. The file name and category are unchanged. The next access of that file is treated as the first access to it.
End of Report
At the end of Report execution, if the Report includes an Extract command for an Extract file:
All TEMPORARY files created by the Report are deleted.
For PERMANENT files:
If that file has been accessed in the Report, the file is closed.
If that file has not been accessed in the Report, the file is cleared (if it already exists), or created as an empty file (if it does not exist).
For EXISTING files:
If that file has been accessed in the Report, the file is closed.
If that file has not been accessed in the Report, no action is taken.
The following table shows the actions performed at end-of-job on Extract files for which an Extract command was included.
| State of file | TEMPORARY | PERMANENT | EXISTING |
|---|---|---|---|
| File exists and has been accessed | Deleted | Closed | Closed |
| File exists and has NOT been accessed | Deleted | Cleared | Closed |
| File does not exist | No action | Created | No action |
If the Report does not include an Extract command for an Extract file:
All TEMPORARY files created by the Report are deleted.
For PERMANENT or EXISTING files:
If that file has been accessed in the Report, the file is closed.
If that file has not been accessed in the Report, no action is taken.
The following table shows the actions performed at end-of-job on Extract files for which an Extract command was not included.
| State of file | TEMPORARY | PERMANENT | EXISTING |
|---|---|---|---|
| File exists | Deleted | Closed | Closed |
| File does not exist | No action | No action | No action |