Introduction to the Frustrum

Chapters

File Handling >>>

Contents

• 1.1 Introduction
  • 1.1.1 Dummy frustrum
• 1.2 Summary of functions
  • 1.2.1 Initialization
  • 1.2.2 Memory management
• 1.3 Abort recovery
• 1.4 Frustrum errors
  • 1.4.1 Prediction errors
  • 1.4.2 Exception errors
  • 1.4.3 Illegal call errors
• 1.5 Validation tests
  • 1.5.1 TESTFR - invokes the verification tests for the frustrum

[back to top]

1.1 Introduction

The Frustrum is a set of functions which must be written by the application programmer. They are called by Parasolid to perform the following tasks:

• Frustrum control
• File (part data) handling
• Memory handling
• Graphical output
• Foreign Geometry support (if required)

Detailed information on the Frustrum's file handling functionality is in Chapter 2, "File Handling".

The standard format of file headers which the Frustrum should read and write is described in Chapter 3, "File Header Structure".

This chapter introduces the Frustrum functions; their interfaces are defined in Appendix A, "Frustrum Functions".

[back to top]

1.1.1 Dummy frustrum

The code for a dummy frustrum is supplied with the release in the file frustrum.c . This example gives a feel for how a Frustrum might be implemented, although the complexity of a Frustrum is dependent on its application. The example Frustrum has three purposes:

• To build and run the Parasolid installation acceptance test program.
• To let you build and run simple prototype applications without having first to write a complete Frustrum.
• To help you write you own frustrum.

To further help you write your own frustrum, the Parasolid Example Application also contains source code for a frustrum implementation on Windows NT. See the Getting Started With Parasolid manual for more details.

[back to top]

1.2 Summary of functions

This table summarizes the frustrum functions which you must provide.

[back to top]

1.2.1 Initialization

The Frustrum is initialized by calling FSTART and is closed down by FSTOP.

The former is called by PK_SESSION_start and the latter by PK_SESSION_stop. Parasolid does not call any other Frustrum functions before the Frustrum has been initialized nor after it has been closed.

[back to top]

1.2.2 Memory management

Parasolid needs to be able to allocate and free virtual memory into which to put its model data. The Frustrum interface to this facility is provided by the FMALLO and FMFREE functions, and is similar to the C library functions malloc and free .

The amount of virtual memory that Parasolid requests depends on the complexity of the modeling operation. By default, the minimum is about 1/8 Mbyte. You can set and enquire the current value of this minimum block of memory using the functions PK_MEMORY_set_block_size and PK_MEMORY_ask_block_size, respectively. For complex cases, or those which require a lot of data storage, Parasolid may request more.

[back to top]

1.3 Abort recovery

Following an interrupt, the application has the option of calling KABORT before allowing Parasolid to continue processing. This causes it to abort the operation which was in progress. The call to KABORT would be made by an interrupt handler provided by the application.

Following such an abort, Parasolid normally returns through the PK in the normal way, giving error PK_ERROR_aborted. Before returning, Parasolid makes a call to Frustrum function FABORT, which gives the application developer an opportunity to do any generic tidying up and/or to do a long-jump to some special recovery-point within his code.

For further information on abort recovery, see Chapter 58, "Error Handling", of the Parasolid Functional Description manual.

[back to top]

1.4 Frustrum errors

If a Frustrum function detects an error, it returns an error code in its final argument ( ifail ), which otherwise is the code FR_no_errors. The error codes are divided into three categories - prediction, exception and illegal call.

[back to top]

1.4.1 Prediction errors

This category contains those errors which can be expected to occur during the ordinary course of a program run. Parasolid looks for this type of error return code explicitly and takes the appropriate action.

For example, the implementation must always check the key name arguments which are passed to FFOPRD and FFOPWR and the file size argument which is passed to FFOPRB, in case Parasolid is being run with argument validation having been switched off by PK_SESSION_set_check_arguments. These types of errors can be said to be predictable.

The range of prediction error codes which can be returned from a given function are documented as end of line comments to the ifail argument.

[back to top]

1.4.2 Exception errors

This category contains codes for unpredictable but plausible errors.

Where some particular remedial action is possible, Parasolid traps these cases explicitly. If no specific course of action is appropriate, Parasolid traps and handles such cases by a default action.

For example, some PK functions need to take special action in the event of running out of disk space whereas others handle such cases by a catch all error trap.

Exception codes are also added as end of line comments to the ifail argument in the documentation of each Frustrum function.

[back to top]

1.4.3 Illegal call errors

This category is used to report an erroneous call being made to a Frustrum function, such as trying to write to a file strid which has not been opened or to denote that an error has occurred in the Frustrum implementation.

The Frustrum should normally report illegal call errors by outputting a message describing what went wrong, before returning the generic code FR_unspecified.

This code should only be returned when an error has been detected; it should not be set in the normal course of events. For this reason, the ifail code FR_unspecified is not used in the documentation for the Frustrum functions.

If an error occurs which is not the result of an erroneous call being made to the Frustrum or of an internal error in the Frustrum code, the ifail should be set to one the mnemonic codes in the documentation which best describes the result.

Note that the code FR_unspecified is not trapped explicitly by Parasolid, so the resulting ifail code returned from the KI may be misleading.

[back to top]

1.5 Validation tests

The test function TESTFR is supplied with Parasolid to enable the customer to check that the behavior of his implementation of the Frustrum is consistent with the requirements of Parasolid and of file portability.

It is strongly recommended that TESTFR be linked and run every time the Frustrum is changed, and for every new version of Parasolid; Frustrum faults can cause obscure and serious problems in Parasolid.

Although the specification for TESTFR is included with the Frustrum documentation, TESTFR is not itself part of the Frustrum, and as such is not supplied by the customer, but is supplied with Parasolid.

However, the TESTFR function requires a key name server FTMKEY to be provided by the customer implementation, which returns sample names to be used as arguments in the test calls made to FFOPRD and FFOPWR. The key name server is not otherwise used by Parasolid.

[back to top]

1.5.1 TESTFR - invokes the verification tests for the frustrum

void TESTFR
(
                            /* received arguments */
int *number,       /* test number */
int *level,        /* trace level */
                            /* returned arguments */
int *code          /* completion code */
)

This function invokes a set of verification tests for customer implementations of the Frustrum. These are designed to confirm that the behavior of the Frustrum (with respect to file handling and memory management) is consistent with the requirements of Parasolid and of file portability.

The tests are not foolproof, and in particular, cannot detect cases where the Frustrum writes/reads files in a way not compatible with the C run time library. Nonetheless, the tests can detect many Frustrum faults which might otherwise cause obscure and catastrophic problems in Parasolid. It is therefore strongly recommended that a customer runs the tests after any modification to his Frustrum, and after receiving any new version of Parasolid.

In order to run the tests, the customer must provide a simple driver program to call TESTFR, which he then links with TESTFR and with his Frustrum. Once a test image has been linked, the following test strategy is recommended:

• Delete any back copies of test files which have been produced by earlier runs. The names of these files have been determined by the sample key names which were returned by FTMKEY.

For example, if FTMKEY is called with guise = FFCJNL, format = FFTEXT and test index 20, it might return the string "TESTFR_20.jnl_txt". It would be necessary to delete any test files which matched "TESTFR_<index>.<guise>_<format>" (where <index> = 1..20)

Note that the test files are not necessarily created in the same directory (e.g. a Frustrum implementation might choose to write its journal file to the user's default directory but to write its schema files to a common system directory).

• Call TESTFR for test 0 at trace level 0. Note the completion code.
• If the completion code is zero (implying a setup error), check that all of the test files which are implied by FTMKEY have been deleted. Check that the test and trace arguments are being passed correctly to TESTFR (by address) and that the values are in range.
• If the completion code is one, all of the tests have succeeded.
• If the completion code is two (failure), delete any test files which have just been produced and call TESTFR for test 0 at trace level 1.

Note the test number which has failed as N.

Delete any test files which have just been produced and call TESTFR for test N at trace level 2 (or 3). This traces the function arguments which were used (with diagnostics).

Correct the Frustrum implementation, making use of the trace messages (and diagnostics), then return to the first step and start the process again.

• If the completion code is three, this implies that no tests in TESTFR are associated with the given test number; it should be incremented (this is to allow particular tests to be commented out later on).
• If the completion code is four, this implies that the given number exceeds the number of tests which have been defined for TESTFR. If running with the test number as zero, this message shows up at the end of the level one trace, all the tests have been tried.
• If the completion code is five, all of the tests have succeeded but a warning has been noted; delete any test files which have just been produced and call TESTFR for test 0 at trace level 3 (writing the trace output to a log file). Search the file for the word 'Warning'. Check with the Parasolid Technical Support group if the reason for the warning is not apparent from the trace messages and Frustrum documentation.

The association between a particular check and a test number will not necessarily be maintained between releases of Parasolid and/or releases of the Frustrum interface specification.

[back to top]