previous next top contents index framed top this page unframed
Figure 42–8. $newRecords (GENERIC)
| POINTER PROCEDURE $newRecords (POINTER p; STRING linkFieldName; LONG INTEGER numRecords; OPTIONAL BITS ctrlBits; OPTIONAL POINTER($area) area); POINTER PROCEDURE $newRecords (POINTER p; INTEGER linkFieldDspl; LONG INTEGER numRecords; OPTIONAL BITS ctrlBits; OPTIONAL POINTER($area) area); BOOLEAN PROCEDURE $newRecords (POINTER p; POINTER ARRAY(*) ary; OPTIONAL LONG INTEGER numRecords; OPTIONAL BITS ctrlBits; OPTIONAL POINTER($area) area); |
$newRecords may be used to allocate more than one dynamic record at a time. If there are many records to be allocated, $newRecords is more efficient than repeated calls to new. The POINTER-valued forms of $newRecords return a POINTER to the first record in the allocated linked list of records; the ARRAY form allocates dynamic records and sets the elements of ary to point to them. The records allocated are of p's CLASS; p may point to either a record of the desired CLASS or the CLASS descriptor for the CLASS. numRecords records are allocated; in the ARRAY form, if numRecords is less than or equal to 0L, one record is allocated for each element of the ARRAY.
The STRING form links the records together through a POINTER link field of name linkFieldName in each record. The ARRAY form sets the elements of ary to point to the allocated records, starting at the lower bound of ary. Any unused elements are unaffected. The INTEGER form allows the link field to be specified by its offset in the record rather than by the name of the field. It is slightly more efficient than the STRING form if the field offset is known at compiletime.
The only valid ctrlBits bit is errorOK; if set, an error message is suppressed if space cannot be allocated for the records. An error occurs and a Zero value is returned if any of the following is true:
area specifies the area in which the newly allocated records are put.
MAINSAIL Language Manual, Section 42.6