Consistency Enhancements to R/LIST for Advanced Revelation 2.0

In response to a need for improved report consistency controls and in specific response to requirements or limitations imposed by bonding and to improved file error handling capabilities, two enhancements have been made to R/LIST.

R/LIST now accepts a lock option (L) that locks all files involved in the query. Because R/LIST accepts only the primary data file to be specified, all other related files must be inferred. When R/LIST encounters the first access to a file via an XLATE function call, the file is locked. After the LIST, SELECT, COUNT, or other R/LIST process has completed, the locks are removed and the locking flag is turned off. Subsequent XLATE calls will not lock the file.

Note: Symbolic fields that extract data from other files through some means other than XLATE do not lock files.

If the file lock is held by some other workstation or process, R/LIST or XLATE will retry the lock. After a given number of retries (currently 200), a message displays indicating the file for which the station is waiting. You can press [Esc] to terminate the query.

R/LIST or XLATE will also terminate the query after the time specified in the Environment Concurrency window Lock Timeout prompt. If the time specified in the Lock Timeout prompt is 0, the lock will be retried indefinitely.

Note: Record locks do not normally conflict with file locks. To have R/LIST detect record locks, you need to specify 'coordinated' locking for the file or files in question. You can do this for a single window by setting the appropriate lock type in Paint, or generically by setting the coordinated locking option in the Environment-Global window.

If a record cannot be read because of a problem other than corruption of data or failure of the operation of the filing system, the error is considered a 'logical read error'. Certain logical error conditions are fairly common in certain bonds. For example, unlike Linear Hash records, records in a dBASE file cannot be read if they are locked.

R/LIST has been enhanced to alert you that potentially important data does not appear in the report. If any logical read error is encountered while performing a LIST statement, R/LIST includes the error number and record key in the report, something like this:

                   *** Error nnn reading record key ***

where the error number is the code returned by the filing system for that failure. These codes typically represent errors that have corrsponding messages in the SYS.MESSAGES file.

At the end of the report, a message reporting the number of errors encountered appears under the count of records processed:

                 * nnn Read Errors encountered in report *

If R/LIST encounters physical or fatal errors during READNEXT or READ operations output, it terminates the report after printing the message:

                  *** Fatal Error reading record key ***

R/LIST verbs that do not create output directly can also report errors. For example, the SELECT verb reads records in order to resolve an active select list.

If logical errors are encountered, the record keys of the records in question are placed into the output list. If you have not used the suppress message option (S), a message displays indicating the number of records selected and, below that, the number of errors encountered. The message will be an A type message. If physical or fatal errors are encountered in select list resolution, the standard I/O error handler is called.

If sorting is specified by the SELECT or LIST statement and indexes are not fully used, the module EXTERNAL.SORT must read all of the records specified. If logical errors are encountered in READNEXT or READ while sorting, a list of up to 32K of keys (including delimiters) is assembled. This list is then concatenated to the end of the sorted list of keys. This is done so that the user will see, at report time, the records that caused read errors. If the error key list exceeds the specified length, the select is terminated with an appropriate file error code.

If a logical error is transient, it is possible (as in the case of dBASE record locks) that the read may fail during the sort process but succeed in the subsequent report. This may cause anomalies such as records out of order in the report. To avoid this problem in the case of dBASE locking, use the file lock option.