Declaring a temporary field to be automatically updated with each cycle¶

!auto

Declare a temporary field whose value is automatically assigned at the start of each logic cycle

SYNTAX

!auto field_id, [”heading”], type & size [[dim1 [,dim2 [,dim3 [,dim4]]]]] \

[/logical] [, “format” [,flags [, “validation”]]] = expression

Declare a automatic temporary field for use in the program. The value of the field is reassigned automatically at the beginning of each cycle of the report driving logic; that is, whenever a new record is read from the driving file. Its initial value is null (0 if the !auto field is numeric, or an empty string if it is alphanumeric).

!auto statements may be mixed with !xfile, !select and !exclude statements. All these are control statements which are executed immediately after each record is read from the driving file. Note that the statements are executed in exactly the same order as they appear in the program. If an !exclude condition evaluates to TRUE (non-zero), processing of all these control statements stops immediately, and the next set of records is read from the driving file.

The !auto declaration has the same structure as !temp:

field_id	The identifier name by which the temporary field will be known. Automatic temps are allocated to the record structure auto, which may be used as the identifier prefix. So the field declared as: !auto SampTot,,u4 can be referred to either as “SampTot” or as “auto.SampTot”. The latter form is essential if “SampTot” is not unique as an identifier within the program, and is in any case recommended, as it avoids possible conflicts arising if new files are added to the program.
heading	The default heading to be used if the field is printed. Must be enclosed in quotes. Two consecutive commas at this point cause the field_id to be used as the heading.
type & size	Any valid Sculptor data type, except p (pointer) or o (object pointer).
dim	The number of subscripts the field is to have, in up to four dimensions. The subscripts are enclosed in square brackets, with each dimension separated by commas. Subscripts are rarely useful for automatic temps - see NOTES below.
logical	Defines the field as a special logical type, such as date or time.
format	A template controlling the specific format to be used when the field is printed. The format must be enclosed in quotes. Two consecutive commas indicate that no special format is required, in which case the default for the field type and size will be used. See also Print: Format.
flags	One or more flag characters specifying more general formatting operations. Flag characters are not enclosed in quotes. Two consecutive commas indicate that no flags are required. See also Print: Flags.
validation	A validation list indicating the acceptable values for the field. Optional.
= expression	This clause defines an expression which should evaluate into a suitable value for assignment to the field. The field is updated by re-evaluation and assignment of expression after each record is read from the driving file. If expression fails a validation test, either by resulting in a value inappropriate to the field’s type & size, or by failing to fall within the values defined in its validation, the appropriate null value is assigned.

See Structure of a data field for more information.

Common uses for !auto

To control !on starting and !on ending statements. These define sections of code which are only executed when the value of the !auto field changes.
To count the number of records in a file, or to total all values of a particular field. These may usefully be compared with the corresponding values for selected records, which are accessed via the Sculptor system variable sys.RecordCount and by the total function.
To check any values unrelated to the selection/exclusion procedure. In example 3 below, a !auto statement is used to count the number of records which have no date supplied, though the selection criteria relates to a reference code.

NOTES

An !auto declaration must appear in the program code before any statements which use it.
!auto statements may be mixed with !xfile statements, which define cross reference files to be read at the start of each logic cycle by means of a field list. A !auto field may be used in an !xfile field list, and a field from a !xfile may be used in the expression clause of a !auto field. Therefore it is essential that these statements appear in the right order. Assignation to !auto fields and reads from files defined with !xfile are performed in the order in which the statements appear in the program.
The total size of all !auto fields is limited to 65,535 bytes.
The startrec and endrec commands may be used to define starting and ending file positions for the driving file. In such cases, unlike exclusions imposed by !select and !exclude statements, a !auto field cannot be used to total, count or check records from the whole file, as records with keys lower than the starting position or higher than the ending position are never read.
It is possible, though rarely useful, to assign dimensions to an automatic temp. The value of expression is assigned to the element referenced by the current value of sys.Row (if the field has a single dimension); if it is multi-dimensional the values of sys.Col, sys.Row, sys.Plane and sys.Dim3 determine the element referenced. Note that !on ending and !on starting declarations may not be allocated subscripts, and always check the first element of an automatic temp.
If an !auto declaration appears outside a !report section, a compiler error is generated.

EXAMPLES

Count the number of records in the driving file:
```
!auto TotRecs,,i4 = TotRecs + 1
```

Total the values of a field:

!auto GrandTotal,,i4 = GrandTotal + Sales.Invtotal

Count records in which a particular field is blank:

!auto NoDates,,i4 = NoDates + (Times.startdate = 0)
!select if (Cust.ref bw "B")

RELATED TOPICS

Reports

!temp