File classes

One of the great strengths of SOUL is the tight integration of the database Manipulation Language, often abbreviated DML, with the programming language. That is, statements like Find, For Each Record, and For Each Occurrence can be easily embedded in SOUL procedure code. Embedding some of these statements in methods, however, can be problematic, and it would be very useful to have object-oriented versions of some standard SOUL file-oriented facilities.

For example, one could execute a Find statement inside a method:

class customer ... subroutine getRecords custRecs: in file customer fd custid = %custId end find ... end subroutine end class

But it would be impossible to use such a found set between methods in the class or to hold the locks on the records while an instance of a customer object exists. Similarly, it might be useful to be able to hold a record open for an instance of a class.

SOUL provides these capabilities with record set, record, and sorted record set objects. The classes, associated with Model 204 file structures, are called file classes, though they can also reference groups.

The names of these classes are:

• Recordset
• Record
• RecordsetCursor
• SortedRecordset

Declaring file objects

One unusual aspect of file classes is that a reference to a file object will not only affect the statement in which it appears, but will sometimes establish a context for the compiler to resolve field names. For this to be accomplished, the file or group context of a file object must be known at compile-time, so this context must be specified in a file object declaration. The syntax of this declaration follows:

{variable} [Is] Object fileClassName - In [ [Perm | Temp] Group | File ] fgname - [ Array(arraySize) ] [ Global[(globalName)] ]

variable	The name of the file object variable. If outside a class declaration block and structure, the variable must begin with a percent sign (%). If inside a structure declaration, the variable must not begin with a percent sign. If inside a class declaration block, the variable cannot start with a percent sign and must be preceded by the word Variable.
fileClassName	The name of a file class. Options are the Recordset, Record, RecordsetCursor, and SortedRecordset classes.
fgname	The file or group name. If this name is not preceded by keywords that explicitly identify the file or group context, the Model 204 search ordering is followed to determine the reference context: temporary groups first, then open permanent groups, then open files.
arraySize	The number of elements in the object array, if it is an array.
globalname	The optional global name, if the collection variable is not a class or structure variable. If Global is specified without globalName, the name of the variable without a percent sign is used as the global name. An object array cannot be Global.

Because they are objects, file objects can be assigned or compared to each other, but only if the variables have the same class and the same file/group context. As just two examples, you cannot assign a Record object variable to a Recordset object variable, and you cannot assign a Recordset In File Ccasys object variable to a Recordset In Group Customer object variable.

When invoking a shared method in a file class using the class name, the file/group context must be specified along with the class name:

%productRec is object record in file products ... %productRec = %(record in file products):new(%n)

This example can also be written, of course, as:

%productRec is object record in file products ... %productRec = new(%n)

DeepCopy for file objects

The Record, Recordset, and SortedRecordset objects are deep-copyable. This means that these objects can be contained inside SOUL classes and those classes, themselves, could be deep-copyable.

Perhaps even more importantly, this means that these objects can be passed back and forth between master and daemon threads, via the Run, GetInputObject, ReturnObject, and ReturnInfoObject methods. Among other things, this makes it easy to dynamically generate Find statements that run on a daemon thread and then use the resulting found set on the master thread:

b %recs is object recordSet in file sirfiled %daem is object daemon %program is object stringList %criteria1 is string len 32 %criteria2 is string len 32 %criteria1 = 'rectype eq FILE' %program = new text to %program b %recs is object recordSet in file sirfiled find records to %recs {%criteria1} {%criteria2} end find  %(daemon):returnObject(%recs) end end text %daem = new %daem:open('FILE SIRFILED', default=true) %daem:run('*LOWER') %daem:run(%program, , %recs) print %recs:count end

Request cancelled if group field reference is nonsensical for file

One of the benefits of the SOUL File classes is easier migration between file-context and group-context SOUL. In most cases, this is provided by allowing the same SOUL code to operate whether in file or group context.

However, there is an opportunity for undetected errors when migrating an application from file to group context. One flexibility of Model 204 groups is that field definitions of the individual files can differ. In particular, a field can be missing in file “A” yet defined in at least one other group member, or it can be defined as INVISIBLE in file "A" and yet defined and not INVISIBLE in at least one other group member. When "A" is the current file, both of these situations can result in nonsensical references to the value of that field, or nonsensical updates to that field.

Your applications are protected against nonsense field references when done in the context of SOUL File objects. The general (but not exact — see "Exact rules of group field cancellation") guideline is that the request is cancelled if both these conditions exist:

• A record is referenced in a group context bound to an object of one of the File classes.
• A field in the record is referenced which would not be allowed if the reference were made in single file context using the current file.

For example, consider the following field definitions and group definition:

IN FILE F1 DEFINE FIELD ONLY1 IN FILE F1 DEFINE FIELD VIS1 IN FILE F2 DEFINE FIELD VIS1 WITH INVISIBLE ORDERED CREATE TEMP GROUP G FROM F1, F2 PARAMETER UPDTFILE F1 END GROUP

Each of the SOUL statements within the following For Each Record will result in compilation errors:

In File F2 For Each Record Print ONLY1 Add ONLY1 = 'Field only in file F1' Print VIS1 Delete VIS1 End For

These are illegal because:

• You cannot refer to a field that is not defined (Print ONLY1 and Add ONLY1).
• You cannot refer to the value of a field that is INVISIBLE (Print VIS1).
• You cannot delete, by occurrence, a field that is INVISIBLE (Delete VIS1).

If you convert this application (which does not use the SOUL File classes) to use a group, it compiles and evaluates without any complaint:

In Group G For Each Record Print ONLY1 Add ONLY1 = 'Field only in file F1' Print VIS1 Delete VIS1 End For

However, when the current file in the For Each Record loop is F2, the following occur, and this may be an application error:

• The value (Print ONLY1) of an undefined field is the null string.
• Updates to undefined fields (Add ONLY1) are ignored.
• The value (Print VIS1) of an INVISIBLE field is the null string.
• A certain class of updates to undefined fields (Delete VIS1) are ignored.

SOUL takes a more conservative approach to handling fields that are undefined or INVISIBLE in some members of a group, when the field references are in records that are bound to an object in one of the File classes.

Using this protection, the following request is cancelled when the first record in file F2 is processed:

Begin %rs Object Recordset In Group G In Group G Find To %rs End Find For Each Record In %rs Print ONLY1 End For End

Similarly, the request is cancelled when processing the first record in file F2 if the statement in the For Each Record loop is any of the following:

Add ONLY1 = 'Field only in file F1' Print VIS1 Delete VIS1

The above request cancellations detect two likely errors: either the field definitions in the group members are incorrect, or the application lacks a way to determine when it makes sense to execute statements with references to fields undefined or INVISIBLE in some members of the group. One way your application can make this latter determination is shown in "Using Is Defined and Is Visible to avoid cancellation".

The exact request cancellation conditions introduced are shown in the next subsection.

Exact rules of group field cancellation

If the following conditions exist:

• A record is referenced in group context.

and

• A record is referenced in a group context bound to an object of one of the File classes.

and

• Using that record reference, a field is referenced in a statement (or expression) other than one of the following:

  Count Occurrences (CTO) For Each Occurrence (FEO) Delete Each Is [Not] Present Is [Not] Defined Is [Not] Visible $Field_Image (that is, an item of the argument 1 Image) $Field_ListI(that is, an item of the argument 2 Image) Sort Records

and

• One of the following conditions exist:
  • The field is not defined in the current file.

  or

  • The field is INVISIBLE in the current file and the value of the field is referenced.

  or

  • The field is INVISIBLE in the current file and is referenced in a Note statement.

  or

  • The field is INVISIBLE in the current file and the field is updated by a CHANGE field To newval (not CHANGE field = oldval To newval) statement.

  or

  • The field is INVISIBLE in the current file and the field is updated by a DELETE field occurrence (not DELETE field = value) statement.

Then the request will be cancelled.

Note: In addition to the list of statements above (CTO, FEO, etc.) which do not cause request cancellation, a few updating statements are shown in the next list, and updating statements for INVISIBLE fields are shown in the list after that, which do not cause request cancellation.

Other statements that do not cancel request

One of the conditions that is necessary for request cancellation due to nonsensical field references is that a record referenced in a group context is bound to an object of one of the File classes, and that a field is referenced using that record. The following SOUL statements refer to fields but are not in a record context, so they are not subject to the SOUL nonsensical-field-reference protection:

• Store Record
• File Records Under
• For Each Value
• Find Records
• Find And Print Count
• Where and Order By clauses of For Each Record
• Find Values

Also, the following updating statements are allowed for INVISIBLE fields, so they do not cause request cancellation if the field is INVISIBLE in the current file:

• Add
• Change field = oldval To newval
• Delete field = value
• Insert

Using Is Defined and Is Visible to avoid cancellation

Using the same field and group definitions from "Request cancelled if group field reference is nonsensical for file", here is a SOUL request that skips nonsensical field references:

Begin %rs Object Recordset In Group G In Group G Find To %rs End Find For Each Record In %rs If ONLY1 Is Defined Then Print ONLY1 Add ONLY1 = 'Field only in file F1' End If If VIS1 Is Visible Then Print VIS1 Delete VIS1 End If End For End

Note that this is not the same result as the second SOUL example (In Group G For Each Record) in "Request cancelled if group field reference is nonsensical for file". In that example, two blank lines are printed for each record in file F2 (by the Print ONLY1 and Print VIS1 statements).