4.1. $structureCompare

$structureCompare can be used to compare two structures. It returns TRUE if and only if root1 and root2 point to “equal” structures, where structures are recursively defined to be equal as follows:

• Two records are equal if they have the same CLASS (CLASS names and all field names are the same, and fields are in the same order and have the same data type) and if all corresponding fields are equal or point to equal structures (for non-ARRAY and non-POINTER data types, x and y are equal if the MAINSAIL expression x = y is TRUE).

• Two ARRAYs are equal if the have the same data type, dimension, and bounds, and if all corresponding elements are equal or point to equal structures.

• $structureCompare of data sections is not currently fully implemented. $structureCompare will consider two data sections unequal if they are for different modules or any interface, outer, or OWN variables are different, but may also consider two data sections unequal when no information visible to the ordinary programmer is different. At present, do not include data sections in any structures to be compared with $structureCompare.

$structureCompare may need to allocate additional data structures to do the comparison. The only valid ctrlBits bit is errorOK, which suppresses error messages.

The results of comparing structures containing any MAINSAIL runtime data structures (e.g., file POINTERs or runtime system data sections) are undefined.

4.2. $structureCopy

$structureCopy returns a copy of the structure to which root points. NULLPOINTER is returned if and only if an error occurs. If area is specified, the dynamic objects of the data structure are copied into area; otherwise, they are copied into $defaultArea.

The only valid ctrlBits bits are delete, errorOK, and $charsInArea. If errorOK is set, error messages are suppressed. If delete is set, the structure pointed at by root is disposed after being copied, as if $structureDispose(root) were performed immediately after the call to $structureCopy. If $charsInArea is set and area is specified, STRING text is copied into area along with dynamic objects; otherwise, STRING text is copied into $defaultArea.

The structure to be copied must not contain any MAINSAIL runtime data structures (e.g., file POINTERs or runtime data sections), since copies of such structures may be invalid; their use has undefined effects.

4.3. $structureDataToText

$structureDataToText translates a data image in inFile to a text form in outFile, starting at the current position in outFile. The data image is located at inFile file page (if $nonPaged is not set in ctrlBits) or inFile file position (if $nonPaged is set in ctrlBits) inputStartPageOrPos. The size of the data image in pages (if $nonPaged is not set in ctrlBits) or storage units (if $nonPaged is set in ctrlBits) is returned in inputNumPagesOrSize. FALSE is returned if and only if an error occurs.

The only valid ctrlBits bits are errorOK, $nonPaged, and $compressed. If errorOK is specified, error messages are suppressed when an error condition occurs. If $nonPaged is set, the structure is not page-aligned. $nonPaged must be set if and only if the structure was written with $nonPaged set; otherwise, the effects are undefined. If $compressed is set, a compressed text form is produced instead of a noncompressed text form.

4.4. $structureDispose

$structureDispose disposes of the structure to which root points. The root POINTER is modified to be NULLPOINTER.

All dynamic objects in the data structure are disposed. This is a convenient way of disposing of an arbitrarily linked data structure.

The only valid ctrlBits bit is errorOK. If specified, error messages are suppressed when an error condition occurs.

The effects of disposing a structure containing POINTERs to file records or other data structures used by the MAINSAIL runtime system are undefined. Use $structureDispose (or the delete option to $structureWrite) only if the structure to be disposed is known not to contain any POINTERs to MAINSAIL runtime data structures.

The results are undefined of calling $structureDispose on a structure containing a data section of which the FINAL PROCEDURE disposes of any component of the data structure. The FINAL PROCEDURE associated with the data section is executed during the call to $structureDispose; if some dynamic object disposed by the final PROCEDURE is also contained in the structure, then that object is effectively disposed twice. Any OWN variables contained in the data section (whether interface variables or not) are considered to be contained in the structure.

The results are undefined of calling $structureDispose on a structure containing a bound data section.

If a structure can be easily disposed by repeated calls to the PROCEDURE dispose (e.g., a singly-linked list), or if the entire structure is in a single area than can be disposed with $disposeArea, it is more efficient to do so than to call $structureDispose. Call $structureDispose only for structures that are difficult to traverse and in an area that is not to be disposed.

4.5. $structureInfo

$structureInfo returns information about a data or PDF image in f. startPageOrPos indicates where the image starts in the file. It is interpreted as the number of the first page of the image, where 0L is the first page in the file, if the $nonPaged bit is not set in ctrlBits and the image in the file is a data image; otherwise, it is interpreted as a file position. NULLPOINTER is returned if f is a text file and the image is not a PDF image or if f is a data file and the image is neither a PDF nor a data image.

$imageType is $dataImage if the image is a data image or $pdfImage if the image is a PDF image. $version is the version of the image in f. The version numbers for different image formats are not related to each other or to the MAINSAIL version number. $date and $time specify the date and time, respectively, at which the image was written. $numPagesOrSize is the image size (number of pages if the image is a paged data image, number of storage units if the image is a nonpaged data image, or number of character units if the image is a PDF image).

errorOK and $nonPaged are valid in ctrlBits. If errorOK is set, error messages are suppressed. The $nonPaged bit should be set in ctrlBits if and only if it was set when the structure was written; otherwise, the effects are undefined.

XIDAK reserves the right to add new fields to $structureInfoCls.

4.6. $structureRead

$structureRead reads a structure from f and returns a POINTER to the structure. NULLPOINTER is returned if and only if an error occurs. The image in a data file can be either a data image or a PDF image and the image in a text file can be either a text form or a PDF image.

In both the dataFile and textFile forms, $pdf is valid in ctrlBits. If this bit is set or if the file is open for PDF I/O, then $structureRead reads a PDF image from the file. If $pdf is not set in ctrlBits and if the file is not open for PDF I/O, $structureRead automatically determines the format of the image in the file and reads it accordingly. This automatic detection introduces some overhead during $structureRead. Also, the heuristic used to detect what type of image resides in the file is not foolproof and could give the wrong result. For these reasons, the $pdf bit should be specified if the image is known to be a PDF image.

If area is specified, the structure is allocated in the specified area; otherwise, it is allocated in $defaultArea.

In the dataFile form, startPageOrPos indicates where the image starts in the file. It is interpreted as the number of the first page of the image, where 0L is the first page in the file, if the $nonPaged bit is not set in ctrlBits and the image in the file is a data image; otherwise, it is interpreted as a file position. In the textFile form, the structure is assumed to start at the current file position.

In the dataFile form, numPagesOrSize is used if the image in the file is a data image. It is ignored if the image in the file is a PDF image. numPagesOrSize specifies the image size. It is interpreted as the number of storage units in the image if the $nonPaged bit is set in ctrlBits; otherwise, it is interpreted as the number of pages in the image. If numPagesOrSize is 0L, then $structureRead obtains this information from the image in the file. An error occurs if numPagesOrSize is nonzero and does not agree with the value stored in the image. It is never necessary to specify numPagesOrSize, since $structureRead can obtain the image size from the image in the file. However, $structureRead is more efficient if numPagesOrSize is specified, since it then does not have to read the first part of the image into memory just to obtain the image size.

In the dataFile form, actualNumPagesOrSize is the image size. It is the number of character units if the image is a PDF image, the number of storage units if the image is a data image and the $nonPaged bit is set in ctrlBits, or the number of pages if the image is a data image and the $nonPaged bit is not set in ctrlBits.

When the dataFile form returns, the current file position of f is immediately after the structure.

In the textFile form, the image is assumed to start at the current file position. A text image must be terminated by a page mark (eop character) or end-of-file. When $structureRead returns from reading a text image, the current file position is immediately after the terminating page mark or at end-of-file.

errorOK is valid in ctrlBits in both the dataFile and textFile forms. If errorOK is set, error messages are suppressed.

In the dataFile form, $nonPaged and $charsInArea are valid in ctrlBits. $nonPaged indicates that the structure is not page-aligned and should be set in ctrlBits if and only if it was set when the structure was written; otherwise, the effects are undefined. If $charsInArea is set and area is specified, STRING text is put in the specified area; otherwise, STRING text is put in $defaultArea.

In the textFile form, warning and keepNul are valid in ctrlBits. They are used if the image in the file is a text image and are ignored if the image is a PDF image. If warning is set, a warning is given for any fields encountered in a record unit but not declared in the corresponding CLASS unit. The values specified for such fields are not used. If keepNul is set, character codes in STRING constants expressed as \ followed by one or more digits are not translated to the host character set; instead they retain the decimal values specified (high-order bits are discarded if host characters have more bits than target characters). If keepNul is not set, character code translation is performed on \-digit escape sequences. Character code translation is always performed on characters not expressed as \-digit escape sequences; if translation is not desired, such characters must be expressed as \-digit escape sequences.

$compressed should not be set in ctrlBits since $structureRead can detect a compressed text image.

When a data section for a module m is read in with $structureRead, the Structure Blaster carries out the same logic as done for new(m), except that:

• The data section read in is used instead of creating a new data section.

• m's INITIAL PROCEDURE, if any, is not invoked because it has already been invoked to initialize the data section when it was first created.

• m's OWN and outer variables are not reset to Zero; they have the same value as they did on the call to $structureWrite.

Note that $SHARED variables are not stored when structures are written, and therefore are not updated when the structure is read in.

m gets linkage to and interface consistency checking is performed on any existing bound modules that it references.

The result of $structureRead is undefined if the structure in the file contains a MAINSAIL runtime data structure (e.g., a file POINTER or runtime system module data section).

4.7. $structureSetup

$structureSetup does preliminary processing on the structure pointed to by root. It returns NULLPOINTER if and only if an error occurs.

The most common use of $structureSetup is to determine the size of a data or PDF image. An application program may need this information, for example, to reserve space in a file for an image. In order to determine the image size, $structureSetup must process the entire structure. The information gathered while processing the structure is returned so that $structureWrite need not process the structure again. If the size of the image need not be known before writing the structure then $structureSetup need not be called ($structureWrite automatically calls $structureSetup if it is not provided with information about the structure).

$structureSetup does preliminary processing for either a data image or a PDF image. Preprocessing is done for a PDF image if the $pdf bit is set in ctrlBits or if f points to a file open for PDF I/O; otherwise, preprocessing is done for a data image.

Note: If f points to a text file that is not open for PDF I/O and the $pdf bit is not set in ctrlBits, the image size in the record pointed to by the result of $structureSetup will be the size of the data image, not the size of the text representation of that image in f, so the application program should not use that size to reserve space in the text file. In fact, there is currently no way to determine how much space a text form will take up without actually writing it.

errorOK, $nonPaged, and $shareStrings are valid in ctrlBits. If errorOK is specified, error messages are suppressed. $nonPaged is used only when setting up for a data image; it is ignored when setting up for a PDF image. If the $nonPaged bit is set in ctrlBits, preprocessing is done for a nonpaged data image; if the $nonPaged bit is not set in ctrlBits, preprocessing is done for a paged data image. If the $nonPaged bit is set in ctrlBits, then it must also be specified in all subsequent calls to $structureWrite, $structureRead, and $structureInfo for root. $shareStrings specifies that only one copy of each different STRING constant is to be written to the image. It can take longer to copy a structure with $shareStrings set, but can save considerable space if many STRINGs in the structure share the same text. If the $shareStrings bit is set in ctrlBits, then it must also be specified in all subsequent calls to $structureWrite for root.

The documented fields of the CLASS $strucInfo describe only part of the information returned by $structureSetup; the other information is useful only to $structureWrite or $structureUnSetup.

The field $totalPagesOrSize indicates the image size. It is the number of character units for a PDF image, the number of storage units for a nonpaged data image, or the number of pages for a paged data image. The result of a subsequent call to $structureWrite or $structureUnSetup is undefined if the information in the record returned by $structureSetup is altered.

The field $imageType can have the value $dataImage or $pdfImage. The meanings are the same as in the field by the same name returned by $structureInfo.

The memory used to store the information returned by $structureSetup is automatically released during a subsequent call to $structureWrite (if passed to $structureWrite in the strucInfo argument). If $structureWrite is not subsequently called, then $structureUnSetup should be called to reclaim the memory.

4.8. $structureTextToData

$structureTextToData translates a text form in inFile to a data image in outFile. The text form is assumed to start at the current position in inFile, and its end is delimited by a page mark or end-of-file, whichever occurs first. The data image is written to outFile file page (if $nonPaged is not set in ctrlBits) or outFile file position (if $nonPaged is set in ctrlBits) outputStartPageOrPos. The size of the data image in pages (if $nonPaged is not set in ctrlBits) or storage units (if $nonPaged is set in ctrlBits) is returned in outputPagesOrSize. FALSE is returned if and only if an error occurs.

Valid ctrlBits bits are errorOK, $nonPaged, warning, and keepNul. warning and keepNul have the same effect as for $structureTextRead. If errorOK is set, error messages are suppressed if an error condition occurs. If $nonPaged is set, the data image is not page-aligned in outFile. If set in a call to $structureTextToData, $nonPaged must be set in all subsequent calls to $structureRead and $structureInfo for the same structure.

4.9. $structureUnSetup

$structureUnSetup disposes of p and all associated data structures and sets p to NULLPOINTER. p must have been returned by a previous call to $structureSetup. $structureUnSetup has no effect if p is NULLPOINTER.

$structureUnSetup should be called to reclaim memory if $structureSetup was called and the structure was not written to a file by a subsequent call to $structureWrite.

There are currently no valid ctrlBits bits.

4.10. $structureWrite

$structureWrite writes the structure pointed to by root to f. The format of the image written depends on the arguments. 0L is returned if and only if an error occurs.

The format of the image written to f is determined as follows:

• If strucInfo is specified, then the format of the image written is determined from the information in the record pointed to by strucInfo;

• Otherwise, if the $pdf bit is set in ctrlBits or if f is open for PDF I/O, then a PDF image is written;

• Otherwise, if the dataFile form of $structureWrite is called, then a data image is written;

• Otherwise, a text form is written.

f must be open for random access if a data image or a PDF image is written.

In the dataFile form, startPageOrPos indicates the starting position of the image in the file. It is interpreted as a page number, where 0L is the first page in the file, if the $nonPaged bit is not set in ctrlBits and a data image is being written to the file. Otherwise, it is interpreted as a file position. In the textFile form, the structure is written beginning at the current file position.

If strucInfo is specified, it must be the value returned by a previous call to $structureSetup for root. If strucInfo is NULLPOINTER, $structureWrite automatically calls $structureSetup to process the structure. Before $structureWrite returns, it automatically calls $structureUnSetup to reclaim memory.

In the dataFile form, the value returned by $structureWrite indicates the size of the image written to the file. It is the number of character units if the image written is a PDF image, the number of storage units if the image written is a nonpaged data image, and the number of pages if the image written is a paged data image. In the textFile form, the value returned is TRUE if the image was successfully written and FALSE if an error occurred.

The file position is left at the end of the image or text form.

errorOK, delete, and $pdf are valid in ctrlBits for both the textFile and the dataFile forms. If errorOK is set, error messages are suppressed. If delete is set, $structureWrite deletes the structure after it is written to the file (as if $structureDispose were called). It may be more efficient to set the delete bit than to call $structureWrite followed by $structureDispose. If the $pdf bit is set in ctrlBits, then a PDF image is written to f.

In the dataFile form, $nonPaged and $shareStrings are valid in ctrlBits. Both the $nonPaged and $shareStrings bits are used when writing a data image; they are ignored when writing a PDF image (the $shareStrings bit may someday be implemented for PDF images, but is not at present). A data image is page-aligned in the file unless the $nonPaged bit is set in ctrlBits. $nonPaged must be set in ctrlBits if it was specified in a previous call to $structureSetup for root. If $nonPaged is set in ctrlBits, then it must also be specified in all subsequent calls to $structureRead and $structureInfo for root.

If the $shareStrings bit is set in ctrlBits then only one copy of the characters for each unique STRING is stored in the image. By “unique STRING” is meant all STRINGs whose lengths are different or whose characters differ; i.e., two STRINGs with STRING descriptors pointing to two different memory locations are not unique if the STRINGs are the same length and contain exactly the same characters. Setting the $shareStrings bit in ctrlBits is an optimization that may save space in the stored image but that may increase the time it takes to write the image. $shareStrings must be set in ctrlBits if it was specified in a previous call to $structureSetup for root.

In the textFile form, $compressed is valid in ctrlBits. The $compressed bit is used when writing a text form; it is ignored when writing a PDF image. If the $compressed bit is set in ctrlBits, then a compressed text form is written.

Accessible nonbound data sections (those created by a call to new) are written out in their entirety, including OWN and outer variables, but not including shared variables (those declared with the keyword $SHARED).

POINTERs that point to free chunks or bound data sections are written as NULLPOINTER. ADDRESS and CHARADR values are written “as is”; such values are not portable, but this allows a program to write a structure that contains ADDRESS or CHARADR values and then read it back into memory during the same MAINSAIL session.

The structure pointed to by root cannot contain any MAINSAIL runtime data structures, such as file POINTERs or runtime data sections. $structureWrite may not fail if root contains such data structures, but the results of a subsequent $structureRead are undefined.

4.10.1. Structures Written Only from Specified Areas

This is accomplished by marking the areas of interest, as described below, and then specifying the $markedAreas bit in the ctrlBits parameter of the $structureWrite call. Marking the areas has no effect unless $markedAreas is set in the $structureWrite call.

An area pointed to by POINTER($area) ap is marked as follows:

ap.$areaAttr .IOR $markedArea;

Note that $markedArea is a LONG BITS constant to be set in $areaAttr, whereas $markedAreas is a BITS constant to be set in the ctrlBits parameter to $structureWrite.

Before setting $markedArea in the desired areas as indicated above, the user should first call the parameterless PROCEDURE $unmarkAllAreas to turn off the $markedArea bit in all existing areas, since this bit may still be set from previous operations (it is sometimes set by the MAINSAIL runtime system).

For example, suppose root points to a data structure that is primarily in the area pointed to by ap, and you want to write out just that part that is inside ap. Do as follows:

$unmarkAllAreas; myArea.$areaAttr .IOR $markedArea;
sp := NULLPOINTER; # MODIFIES POINTER($strucInfo) strucInfoPtr
$structureWrite(f,root,0L,sp,$markedAreas);

$structureWrite locates all objects accessible from root, and then all those accessible from these “secondary” objects, and so forth. If the $markedAreas bit is set in the ctrlBits argument, this locating does not follow into unmarked areas. Thus, objects are located only if they are accessible from a path from root that lies entirely within marked areas. An object that is part of the structure when considering all areas, but that is referenced only from an unmarked area, is not found; indeed, there would be no way to “hook up” such an object to that part of the structure that is only in marked areas.

If $markedAreas is set in a call to $structureWrite, then it must have been set in the corresponding call to $structureSetUp (if there was such a call to $structureSetUp).