A.1 Introduction

This appendix contains the specifications of the Frustrum functions required by the PK functions for file and memory handling.

[back to top]

A.2 FSTART - Start up the Frustrum

void FSTART
(
--- returned arguments ---
int       *ifail   --- Return codes: FR_no_errors
)

This function initializes the Frustrum. It is called from PK_SESSION_start and is the first Frustrum function to be called.

Calls to FSTART and FSTOP may be nested (e.g. when replaying a journal file). Only the "outermost" calls (i.e. the first FSTART call, and the "balancing" FSTOP call) should have any effect. However, once the Frustrum has been closed down, a further FSTART call should cause it to be re-initialized.

Parasolid assumes that FSTART always succeeds; it should always return FR_no_errors.

[back to top]

A.3 FABORT - Called at the end of an aborted kernel operation

void FABORT
(
--- returned arguments ---
int       *ifail   --- Return codes: FR_no_errors
)

This function is called by the kernel following a kernel operation which was aborted by a call to PK_SESSION_abort, when PK_SESSION_abort has been called with the token PK_abort_user_interrupt_c.

FABORT allows the application to do any generic tidying following the abort and/or do a long-jump back to a "recovery-point" within the application code (this is the only case where it is legitimate for a Frustrum function to do such a long-jump).

It may be sensible for applications to call FABORT to clean up their Frustrum after a run-time error has occurred and been returned to the application through the PK or KI. This depends on the design of the application and its Frustrum.

For further details, see PK_SESSION_abort in the PK Interface Programming Reference Manual, and Chapter 58, "Error Handling", in the Functional Description.

[back to top]

A.4 FSTOP - Shut down the Frustrum

void FSTOP
(
--- returned arguments ---
int       *ifail   --- Return codes: FR_no_errors
)

This function shuts down the Frustrum, and is called from PK_SESSION_stop. Calls to FSTART and FSTOP may be nested; in this case only the "outermost" calls should have any effect.

[back to top]

A.5 FMALLO - Allocate virtual memory

void FMALLO
(
--- received arguments ---
int  *nbytes,  --- length of memory region in bytes

--- returned arguments ---
char **memory, --- pointer to start of memory
int       *ifail   --- Return codes: FR_no_errors
)

This function allocates the specified amount of virtual memory (in bytes), returning a pointer to the start address. The memory which is allocated can be accessed using byte addresses in the range memory[0] to memory[nbytes-1].

Where the host machine is sensitive to word-alignment, FMALLO must ensure that the allocated memory begins on a word-boundary.

If the requested allocation cannot be met, error code FR_memory_full is returned, and no space is allocated.

By default, the minimum amount of memory requested 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]

A.6 FMFREE - Free virtual memory

void FMFREE
(
--- received arguments ---
int  *nbytes,  --- length of memory region in bytes
char **memory, --- pointer to start of memory

--- returned arguments ---
int       *ifail   --- Return codes: FR_no_errors
)

This function frees virtual memory, previously allocated by FMALLO.

The pointer to the start of block of virtual memory is which has been returned earlier and the length of the memory region must correspond to the length requested when the allocation was made.

[back to top]

A.7 FFOPRD - Open all guises of file for reading

void  FFOPRD
(
--- received arguments ---
const int  *guise,  --- class of file: FFCSNP, FFCJNL, FFCXMT 
                    ---                FFCXMO, FFCSCH, FFCLNC
const int  *format, --- format code: FFBNRY, FFTEXT
const char name[],  --- key which identifies file
                    ---  terminator not required)
const int  *namlen, --- length of name
const int  *skiphd, --- action required on opening file:
                    --- FFSKHD, FFLVHD

--- returned arguments ---
int       *strid,  --- id for stream on which file is open
int       *ifail   --- Return codes: FR_no_errors, FR_bad_name,
                   --- FR_not_found, FR_bad_header,FR_open_file
)

This function opens all guises of existing files for reading i.e., snapshot, journal, C and Fortran transmit, schema and licence files.

If the skiphd flag is set to FFSKHD, the header data is skipped when the file is opened. This is the mode which is used by Parasolid.

If the skiphd flag is set to FFLVHD, the header data is not skipped when the file is opened; the preamble, the parts data and the trailer are read by subsequent calls to FFREAD. This mode is only used by the TESTFR to validate what has been written by a particular implementation.

The function returns a Frustrum stream identifier or "strid". This is used in subsequent calls to FFREAD and FFCLOS.

[back to top]

A.8 FFOPWR - Open all guises of file for writing

void       FFOPWR
(
--- received arguments ---
const int  *guise,   --- class of file: FFCSNP, FFCJNL, FFCXMT
                     ---   FFCSCH, FFCLNC, FFCDBG
const int  *format,  --- format code: FFBNRY, FFTEXT, FFXML
const char name[],   --- key which identifies file
                     ---   (terminator not required)
const int  *namlen,  --- length of name
const char pr2hdr[], --- part 2 header data 
                     --- (terminator not required)
const int  *pr2len,  --- length of part 2 header data

--- returned arguments ---
int        *strid,   --- id for stream on which file is open
int        *ifail    --- Return codes:  FR_no_errors,
                     --- FR_bad_name, FR_already_exists,
                     --- FR_open_fail, FR_write_fail,
                     --- FR_disc_full
)

This function opens all guises of new files for reading i.e. schema, C transmit, journal snapshot and licence files.

The pr2hdr string contains data to be inserted by the Frustrum into the part 2 section of the file header. See the documentation for PK_FFOPWR_f_t in PK_SESSION_frustrum_t.

The function returns a Frustrum stream identifier or "strid". This is used in subsequent calls to FFWRIT and FFCLOS.

[back to top]

A.9 UCOPRD - Open various guises of file for reading using Unicode key

void  UCOPRD
(
--- received arguments ---
const int  guise,  --- class of file: FFCSNP, FFCXMT, FFCXMP
                   --- FFCXMD, snapshot, C-transmit,
                   --- partition, delta
const int  format, --- format code: FFBNRY, FFTEXT
const PK_UCHAR_t name[],   --- key which identifies file
                           --- (null-terminated Unicode)
const PK_LOGICAL_t skiphd, --- action required on opening file

--- returned arguments ---
int  strid,        --- id for stream on which file is open
int       *ifail   --- Return codes: FR_no_errors, FR_bad_name,
                   --- FR_not_found,FR_bad_header, FR_open_file
)

This function opens various guises of existing part files for reading i.e., C transmit, partition and deltas, and snapshot files, using a Unicode key.

If skiphd is PK_LOGICAL_true (the usual case), the header data is skipped when the file is opened. This is the mode which is used by Parasolid.

If skiphd PK_LOGICAL_false, the header data is not skipped when the file is opened; the preamble, the parts data and the trailer are read by subsequent calls to FFREAD. This mode is only used by the TESTFR to validate what has been written by a particular implementation.

The function returns a Frustrum stream identifier or "strid". This is used in subsequent calls to FFREAD and FFCLOS.

[back to top]

A.10 UCOPWR - Open various guises of file for writing using Unicode key

void       UCOPWR
(
--- received arguments ---
const int  guise,    --- class of file: FFCSNP, FFCXMT, FFCXMP
                     --- FFCXMD, snapshot, C-transmit,
                     --- partition, delta
const int  format,   --- format code: FFBNRY, FFTEXT, FFXML
const PK_UCHAR_t name[],  --- key which identifies file
                          --- (null-terminated Unicode)
const char pr2hdr[],      --- part 2 header data
                          --- (null-terminated)

--- returned arguments ---
int        *strid, --- id for stream on which file is open
int       *ifail   --- Return codes: FR_no_errors, FR_bad_name,
                   --- FR_already_exists, FR_open_fail,
                   --- FR_write_fail, FR_disc_full
)

This function opens various guises of new files for writing i.e. schema, C transmit, snapshot, partition and delta files, using a Unicode key.

The pr2hdr string contains data to be inserted by the Frustrum into the part 2 section of the file header. See the documentation for PK_UCOPWR_f_t in PK_SESSION_frustrum_t.

The function returns a Frustrum stream identifier or "strid". This is used in subsequent calls to FFWRIT and FFCLOS.

[back to top]

A.11 FFCLOS - Close file

void     FFCLOS
(
--- received arguments ---
const int *guise,  --- class of file: FFCSNP, FFCJNL, FFCXMT
                   ---   FFCXMO, FFCSCH, FFCLNC, FFCDBG
const int *strid,  --- Frustrum strid
const int *action, --- type of close: FFNORM, FFABOR

--- returned arguments ---
int       *ifail   --- Return codes: FR_no_errors FR_close_fail 
                   --- FR_disc_full      
)

This function closes a Frustrum file which has been opened with FFOPRD or FFOPWR. If the file is newly created, the calling function can determine whether to retain the file (FFNORM) or to delete it (FFABOR).

[back to top]

A.12 FFREAD - Read from file

void      FFREAD
(
--- received arguments ---
const int *guise,   --- class of file: FFCSNP, FFCJNL FFCXMT,
                    ---   FFCXMO, FFCSCH, FFCLNC
const int *strid,   --- Frustrum strid   
const int *nmax,    --- maximum number of chars to read

--- returned arguments ---
char      buffer[], --- buffer containing read data
int       *nactual, --- actual number of characters read
int       *ifail    --- Return codes:  FR_no_errors,
                    --- FR_read_fail, FR_end_of_file   
)

This function reads from file (starting at the current position of the file pointer) storing a maximum of *nmax characters or bytes in the given buffer and returning the actual number of characters or bytes read as *nactual. The file pointer is incremented by the number of characters or bytes read.

In most cases, the number of characters read equals the number requested, except when the end of file is reached or a read error occurs. If the Frustrum implementation is only able to read a maximum of N bytes (where 0<N<=*nmax) Parasolid detects this condition and makes the necessary follow-up calls to FFREAD (which may affect performance).

If FFREAD reads at least one character, the ifail code is set FR_no_errors (or possibly FR_read_fail). The ifail code FR_end_of_file is only returned when no bytes have been read.

[back to top]

A.13 FFWRIT - Write to file

void      FFWRIT
(
--- received arguments ---
const int *guise,    --- class of file: FFCSNP, FFCJNL, 
                     --- FFCXMT, FFCSCH, FFCDBG  
const int *strid,    --- Frustrum strid  
const int *nchars,   --- number of chars/bytes to write >=0
const char buffer[], --- buffer containing data to write

--- returned arguments ---
int       *ifail     --- Return codes:  FR_no_errors,
                     --- FR_write_fail, FR_disc_full  
)

This function writes the contents of the buffer to file, starting at the current position of the file pointer. The file pointer is incremented by the number of characters or bytes written.

[back to top]

A.14 FTMKEY - Returns sample name keys

void      FTMKEY
(
--- received arguments ---
const int *guise,  --- class of file: FFCSNP, FFCJNL, FFCXMT,
                   ---   FFCXMO, FFCSCH, FFCLNC
const int *format, --- format code: FFBNRY, FFTEXT
const int *index,  --- index for different name keys:
                   ---   negative=supply invalid name
                   ---   positive/zero=supply valid name
--- returned arguments ---
char      name[],  --- key which identifies file
                   ---   (null terminated string)
int       *namlen, --- length of name (max=255) 
                   ---(excluding terminator)
int       *ifail   --- Return codes:  FR_no_errors
)

This function is used by validation TESTFR for testing FFOPRD and FFOPWR.

Different values of index should cause different name keys to be generated.

If index is greater than zero, the function returns valid name keys which are used as arguments to FFOPWR and FFOPRD. The name keys should be chosen such that the files generated by TESTFR can readily be distinguished from other files, and can be (safely) deleted at the end of the test.

If index is less than zero, the function returns invalid name keys - they should be rejected by FFOPWR and FFOPRD with ifail code FR_bad_name.

If the implementation of FFOPWR and FFOPRD does not allow the same name to be used for different guise and format types, the names returned by FTMKEY must take account of the guise and format arguments in the returned string such as by encoding them as part of the name.

The returned names must not exceed 255 characters in length.

[back to top]

<<< Registering the Frustrum

Chapters

Graphical Output Functions >>>