| |
File Handling |
| <<< Introduction to the Frustrum | Chapters | File Header Structure >>> |
Parts modelled in Parasolid are saved to external storage using functions in your application’s Frustrum. Parasolid part files ( transmit or XT files) are intended to fit into an archiving system within your application. This could take the form of a controlled directory structure on the host computer, or some kind of database.
Parasolid also requires facilities to save and retrieve large amounts of data in order to support such operations as saving and restoring snapshots and journalling.
Whilst such facilities could be implemented in a number of ways, they are described here in terms of an implementation based on the use of files provided by the host operating system.
A distinction is made between the name of a key, which is passed by Parasolid as an argument to FFOPRD and FFOPWR (or UCOPRD and UCOPWR for Unicode keys) and the name of a file (which is used internally to identify the Frustrum files to the operating system).
The name of the key which is passed to the Frustrum by Parasolid is exactly the same as the name which has been given in the relevant PK call (PK_PART_transmit, PK_SESSION_transmit, PK_SESSION_start etc.), except in the case of schema files where the key has been generated by Parasolid.
The file name depends entirely on the particular implementation of the Frustrum, but typically this might include the key plus directory prefixes and file extensions as appropriate.
The following filename extensions are recommended for the Frustrum to generate and use.
The Frustrum should test whether a file resides on a DOS style FAT device or a long name NTFS type device before opening the file, and act accordingly. Files can simply be renamed when transferring between the different systems.
Note that the 3 character extensions are shown in the table in upper case for clarity, though the case is ignored.
Parasolid requires the Frustrum to support different types (or guises) of file, represented by six-character integer mnemonic codes.
The following guises are opened for reading by FFOPRD and UCOPRD. The file should already exist, and its contents can be read sequentially by FFREAD.
The following guises are opened for writing by FFOPWR and UCOPWR. A new file is created, and it can be written to sequentially by FFWRIT:
When all of a new file has been written or sufficient of an existing file has been read, the file is closed with FFCLOS. In the case of new files, the call specifies whether or not the new file is to be retained.
There is a standard format for a Frustrum file header, which is described in Chapter 3, “File Header Structure”.
In normal operation, Parasolid only has a journal file open, which is open for writing.
For short periods, Parasolid may need to have up to two more files open. These are either a snapshot file or a transmit file, possibly with its associated schema file.
The Frustrum implementation must therefore allow for three files to be open at the same time for each Parasolid process.
Parasolid supports the use of 16-bit Unicode filenames in your application, as well as the native character set. This is achieved by using the following frustrum functions instead of FFOPRD and FFOPWR:
To use these functions, you must call PK_SESSION_set_unicode before registering the frustrum. Once called, you must then supply valid UCOPRD and UCOPWR functions instead of FFOPRD and FFOPWR functions when registering the frustrum. For more information about registering the frustrum, see Chapter 5, “Registering the Frustrum”.
To find out whether Unicode keys are enabled within a given session, call PK_SESSION_ask_unicode.
Parasolid regards a file as being simply a stream of bytes, which is written or read sequentially. It is assumed that the stream of bytes obtained when reading is identical to that which was written (except in the case of a file ported between systems, when the character set may change).
Parasolid distinguishes between binary files and text files:
isprint
) interspersed with newline characters (corresponding to
\n
in C) such that there are never more than 80 consecutive printing characters.When writing certain files via the Frustrum, the application needs to specify whether they are to be in text or binary format. A file must be written and read in the same format (thus is Frustrum dependent). When deciding which format to use, consider the following factors:
There is also a transmit file format called
application i/o, or
applio. When this
transmit_format
is selected in PK_PART_transmit and PK_PARTITION_transmit, transmit files are written and read using a suite of functions provided by the application. Using these functions enables the application to do further processing of the output data before storing it.
The applio function interfaces are defined in Appendix E, “Application I/O Functions”.
There is also a transmit file format called
indexed i/o, or
indexio. When this
transmit_format
is selected in PK_PART_transmit and PK_PARTITION_transmit, transmit files are written using a suite of functions provided by the application. Using these functions enables your application to subsequently receive only specified faces from the parts contained in the transmitted files.
The indexio function interfaces are defined in Appendix F, “Indexed I/O Functions”.
It is clearly desirable that Parasolid files be portable between different machines and between different systems which use Parasolid (which have different Frustrum implementations). In practice, machine specific binary files cannot be ported from one type of machine to another, so the best that can be achieved is:
In order that files be portable between different Frustrum implementations, it is necessary to standardize the internal format of the file. For this reason, we recommend that all Frustrum implementations should generate files in the same format as is generated by the appropriate C runtime library functions on the appropriate machine. In the case of text files, this includes correct handling of newline (
\n
) characters.
To ensure portability of text files between different machine types, we require that:
isprint
. All text data output from Parasolid conforms to this rule; however, the Frustrum must guarantee it for the Frustrum header data.
\n
) into all text data being output. The Frustrum must ensure sufficient newline characters appear in the Frustrum header.It is also necessary that, when a text file is ported to a different type of machine, it is converted to the local character set and C format for the the target machine.
If a Frustrum implementation does not follow the above recommendations it may prove impossible to read files which have been created by other systems or to forward its own files to other systems (such as when making a fault reporting). Problems of this sort may be revealed by running the Frustrum validation tests, but note that these tests cannot verify that the file format is consistent with the C runtime library, so some additional check is required to confirm that this is the case.
Snapshot files are created by PK_SESSION_transmit. The data within the snapshot files is schema dependent and Parasolid needs to have access to the corresponding schema file in order to interpret it.
Journal files are created as a result of calling PK_SESSION_start with journalling switched on. They are always created in text format. The files are used to record the values of arguments which have been passed to and received from PK and KI functions.
Journal files are reasonably portable between machines, except where the arguments specify such machine dependent features as file names or database keys or where they refer to parts which were created in an earlier session.
Transmit files containing parts, created by PK_PART_transmit. The data within the transmit files is schema dependent and Parasolid needs to have access to the corresponding schema file in order to interpret it.
Schema files are created by Parasolid to have names of the form
sch_
n (where
n represents an integer value).
The integer value is used internally by Parasolid to identify any changes which have been made to the Parasolid schema.
The schema describes the internal data structure which is used to represent part data within the Parasolid model, such as the ordering of geometric data and the relationships between edges and faces.
The Frustrum should store schema files in a separate directory. The KID Frustrum stores them in a directory which is referenced by the P_SCHEMA environment variable.
Note that the Parasolid release includes a set of schema files for all previous versions of Parasolid and for the current version of the Parasolid modeller. This ensures upgrade compatibility of old part files.
Application writers should include a full set of schema files with their product release, including one for the current version of the Parasolid modeller.
In operating systems which have case specific file names the KID Frustrum chooses to write and read the schema archive file in lower case. Any old schema files that are supplied with a release have lower case file names.
Licence files may be used in subsequent versions to check that Parasolid is being used in accordance with the licencing agreement. The validation tests for Frustrum implementations require this guise of file to be supported by FFOPRD & FFOPWR, so that the licence checking capability can be introduced in a later release of Parasolid, without the need to alter the Frustrum interface further.
It is intended that licence files are created in text format; consisting of a standard file header followed by one or more lines of licence checking data.
Transmit files containing a partition, created by PK_PARTITION_transmit and read by PK_PARTITION_receive.
Transmit files containing deltas, created by PK_PARTITION_transmit if the option to transmit deltas is selected. During the transmit, the partition's deltas are opened, read and output to the transmit file (using the delta handling functions registered with PK_DELTA_register_callbacks).
Delta files can only be received in the version they were transmitted in. They are read by PK_PARTITION_receive_deltas_2, if the option to receive deltas later was selected when the relevant partition was read in by PK_PARTITION_receive.
Debug report files are created as a result of calling PK_DEBUG_report_start. They are always created in XML format. These files are used to record information such as the values of arguments passed to and returned by Parasolid functions, as well as embedding relevant part files.
Transmit files containing Persistent Mesh (PSM) mesh data.
There are the basic modes in which files are used by Parasolid.
This mode is characteristic of receiving a Parasolid transmit file, receiving a snapshot file or reading an archived schema file.
A test is made first for whether there is any header data and whether the ‘skip header’ flag is set. If so, the header data is read and checked as deemed necessary by the implementation. If there is no header data or if the header data is to be left (for checking by the Frustrum validation tests), the file pointer is repositioned back to the start of the file.
The file is read sequentially until sufficient data has been read or until the end of file is reached. The file is then closed (and it is retained).
This mode is characteristic of recording a new journal or debug report file.
The file is opened for writing and the header data are written to it. Parasolid then writes sequentially to the file, journalling the arguments to each interface function. The new file is closed and is retained.
If the system crashes while the journal or debug report file is still open, the system is left with a (possibly incomplete) file. Even in its incomplete form, this file can be useful for debugging a session.
This mode is used for creating new transmit, schema and snapshot files.
The difference between the open_protected and the open_new modes is that the Frustrum helps to prevent Parasolid from accessing incomplete or otherwise erroneous files. If an error is detected by Parasolid when writing to a new file, the call to FFCLOS is made with the status code FFABOR, meaning that the file must be deleted when the strid is closed down.
However, if new files are not closed explicitly (as could occur after a system crash), it is possible that a newly created file is not complete.
The Frustrum can protect Parasolid from incomplete files by creating new transmit, schema and snapshot files with scratch names, only giving them their correct identity after the files have been closed explicitly by a call to FFCLOS.
The three basic methods of using files are summarized in the following table:
An entry Y denotes that Parasolid calls the given function in the way which is described by the comment above the column. The file guises XMP and XMD (transmit files containing partition and delta data) use the same methods as XMT (part transmit) files.
Journal files contain the following markup characters to assist with interpretation of the contents.
|
The first and last lines are comment records, which start with a ‘:’ character. |
|
|
The ‘<’ character at the beginning of each journal record is followed by the name of a PK function. This is followed by a sequence of lexical items, being tags, text strings, integers, doubles and punctuation symbols. These are separated by one or more spaces.
|
|
|
A tag is represented by a ‘#’ character, followed by digits. |
|
|
A string is enclosed in quotation marks (two successive quotation marks imply that the string itself contains a quotation mark). |
|
|
Integer values are represented by an (optional) sign, followed by digits. |
|
|
Double values are represented by an (optional) sign, followed by a floating point representation (with a decimal point) or an exponent and mantissa representation (with an ‘e’ character). |
|
| <<< Introduction to the Frustrum | Chapters | File Header Structure >>> |