File classes: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
No edit summary
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<!-- File classes -->
<!-- File classes -->
   
   
One of the great strengths of <var class="product">User Language</var> is the tight integration of the
One of the great strengths of <var class="product">SOUL</var> is the tight integration of the
'''database Manipulation Language''', often abbreviated DML,
'''database Manipulation Language''', often abbreviated DML,
with the programming language.
with the programming language.
That is, statements like Find, <var>For Each Record</var>, and <var>For Each Occurrence</var>
That is, statements like <var>Find</var>, <var>For Each Record</var>, and <var>For Each Occurrence</var>
can be easily embedded in <var class="product">User Language</var> procedure code.
can be easily embedded in <var class="product">SOUL</var> procedure code.
Embedding some of these statements in methods, however, can be problematic,
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 <var class="product">User Language</var>
and it would be very useful to have object-oriented versions of some standard <var class="product">SOUL</var>
file-oriented facilities.
file-oriented facilities.
   
   
Line 28: Line 28:
for an instance of a class.
for an instance of a class.
   
   
The <var class="product">[[Janus SOAP User Language Interface|Janus SOAP ULI]]</var> provides these capabilities with record set, record,
<var class="product">SOUL</var> provides these capabilities with record set, record,
and sorted record set objects.
and sorted record set objects.
The classes, associated with <var class="product">Model 204</var> file structures, are called
The classes, associated with <var class="product">Model 204</var> file structures, are called
Line 65: Line 65:
<tr><th>fileClassName</th>
<tr><th>fileClassName</th>
<td>The name of a file class.
<td>The name of a file class.
<var class="product">Sirius Mods</var> supports the <var>Recordset</var>, <var>Record</var>, <var>RecordsetCursor</var>, and <var>SortedRecordset</var> classes.</td></tr>
Options are the <var>Recordset</var>, <var>Record</var>, <var>RecordsetCursor</var>, and <var>SortedRecordset</var> classes.</td></tr>


<tr><th>fgname</th>
<tr><th>fgname</th>
Line 105: Line 105:
==DeepCopy for file objects==
==DeepCopy for file objects==
The <var>Record</var>, <var>Recordset</var>, and <var>SortedRecordset</var> objects are deep-copyable.
The <var>Record</var>, <var>Recordset</var>, and <var>SortedRecordset</var> objects are deep-copyable.
This means that these objects can be contained inside <var class="product">User Language</var> classes and
This means that these objects can be contained inside <var class="product">SOUL</var> classes and
those classes, themselves, could be deep-copyable.
those classes, themselves, could be deep-copyable.
   
   
Perhaps even more important, this means that these objects can be passed
Perhaps even more importantly, this means that these objects can be passed
back and forth between master and [[Daemon class|daemon]] threads,
back and forth between master and [[Daemon class|daemon]] threads,
via the <var>Run</var>, <var>GetInputObject</var>, <var>ReturnObject</var>, and <var>ReturnInfoObject</var> methods.
via the <var>Run</var>, <var>GetInputObject</var>, <var>ReturnObject</var>, and <var>ReturnInfoObject</var> methods.
Line 147: Line 147:


==Request cancelled if group field reference is nonsensical for file==
==Request cancelled if group field reference is nonsensical for file==
One of the benefits of the <var class="product">Janus SOAP ULI</var> File classes is easier migration
One of the benefits of the <var class="product">SOUL</var> File classes is easier migration
between file-context and group-context <var class="product">User Language</var>.
between file-context and group-context <var class="product">SOUL</var>.
In most cases, this is provided by allowing the same <var class="product">User Language</var> code to
In most cases, this is provided by allowing the same <var class="product">SOUL</var> code to
operate whether in file or group context.
operate whether in file or group context.
   
   
Line 163: Line 163:
references to the value of that field, or nonsensical updates to that field.
references to the value of that field, or nonsensical updates to that field.
   
   
With version 7.0 of <var class="product">Janus SOAP ULI</var>, your applications are
<!-- With version 7.0 of <var class="product">Janus SOAP ULI</var> -->
protected against nonsense field references when done in the context
Your applications are protected against nonsense field references when done in the context
of <var class="product">Janus SOAP ULI</var> File objects.
of <var class="product">SOUL</var> File objects.
The '''general''' (but not exact &mdash; see [[#Exact rules of group field cancellation|"Exact rules of group field cancellation"]])
The '''general''' (but not exact &mdash; see [[#Exact rules of group field cancellation|"Exact rules of group field cancellation"]])
guideline is that the request is cancelled if '''both''' these conditions exist:
guideline is that the request is cancelled if '''both''' these conditions exist:
Line 184: Line 184:
</p>
</p>
   
   
Each of the <var class="product">User Language</var> statements within the following <code>For Each Record</code>
Each of the <var class="product">SOUL</var> statements within the following <code>For Each Record</code> will result in compilation errors:
will result in compilation errors:
<p class="code">In File F2 For Each Record
<p class="code">In File F2 For Each Record
   Print ONLY1
   Print ONLY1
Line 200: Line 199:
<li>You cannot delete, by occurrence, a field that is <var>INVISIBLE</var> (<code>Delete VIS1</code>).
<li>You cannot delete, by occurrence, a field that is <var>INVISIBLE</var> (<code>Delete VIS1</code>).
</ul>
</ul>
If you convert this application (which does not use the <var class="product">Janus SOAP ULI</var> File
If you convert this application (which does not use the <var class="product">SOUL</var> File
classes) to use a group, it compiles and evaluates without any complaint:
classes) to use a group, it compiles and evaluates without any complaint:
<p class="code">In Group G For Each Record
<p class="code">In Group G For Each Record
Line 210: Line 209:
</p>
</p>
However, when the current file in the <code>For Each Record</code>
However, when the current file in the <code>For Each Record</code>
loop is <code>F2</code>, the following occur, and this '''may be an application
loop is <code>F2</code>, the following occur, and this '''may be an application error''':
error''':
<ul>
<ul>
<li>The value (<code>Print ONLY1</code>)
<li>The value (<code>Print ONLY1</code>)
Line 223: Line 221:
</ul>
</ul>
   
   
The <var class="product">Janus SOAP ULI</var> takes a more conservative approach to handling fields that
<var class="product">SOUL</var> takes a more conservative approach to handling fields that
are undefined or <var>INVISIBLE</var> in some members of a group, when the field references are in records
are undefined or <var>INVISIBLE</var> 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.
that are bound to an object in one of the File classes.
Line 311: Line 309:
'''Then''' the request will be cancelled.
'''Then''' the request will be cancelled.
   
   
'''Note:'''
<p class="note">'''Note:'''
In addition to the list of statements above (<var>CTO</var>, <var>FEO</var>, etc.)
In addition to the list of statements above (<var>CTO</var>, <var>FEO</var>, etc.)
which do not cause request cancellation, a few updating
which do not cause request cancellation, a few updating
statements are shown in the next list, and updating
statements are shown in the next list, and updating
statements for <var>INVISIBLE</var> fields are shown in the list after that,
statements for <var>INVISIBLE</var> fields are shown in the list after that,
which do not cause request cancellation.
which do not cause request cancellation. </p>


==Other statements that do not cancel request==
==Other statements that do not cancel request==
Line 322: Line 320:
due to nonsensical field references is that a record referenced in a group context is
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.
bound to an object of one of the File classes, and that a field is referenced using that record.
The following <var class="product">User Language</var> statements refer to fields but
The following <var class="product">SOUL</var> statements refer to fields but
are not in a record context, so they are not subject to
are not in a record context, so they are not subject to
the <var class="product">Janus SOAP ULI</var> nonsensical-field-reference protection:
the <var class="product">SOUL</var> nonsensical-field-reference protection:
<ul>
<ul>
<li><var>Store Record</var>
<li><var>Store Record</var>
Line 346: Line 344:


===Using Is Defined and Is Visible to avoid cancellation===
===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|"Request cancelled if group field reference is nonsensical for file"]], here is a <var class="product">User Language</var> request that skips nonsensical field references:
Using the same field and group definitions from [[#Request cancelled if group field reference is nonsensical for file|"Request cancelled if group field reference is nonsensical for file"]], here is a <var class="product">SOUL</var> request that skips nonsensical field references:
<p class="code">Begin
<p class="code">Begin
%rs Object Recordset In Group G
%rs Object Recordset In Group G
Line 363: Line 361:
End
End
</p>
</p>
Note that this is not the same result as the second <var class="product">User Language</var> example
Note that this is not the same result as the second <var class="product">SOUL</var> example
(<code>In Group G For Each Record</code>) in
(<code>In Group G For Each Record</code>) in
[[#Request cancelled if group field reference is nonsensical for file|"Request cancelled if group field reference is nonsensical for file"]].
[[#Request cancelled if group field reference is nonsensical for file|"Request cancelled if group field reference is nonsensical for file"]].

Latest revision as of 11:45, 13 April 2015


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:

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).