Session Support

115.1 Introduction

This chapter introduces those areas of functionality that an application can use to control and get information about a Parasolid modelling session.

115.2 Session statistics

At any time during a session, information about the state of a modelling session can be returned.

115.2.1 Memory usage

PK_SESSION_ask_memory_usage returns the amount of memory currently occupied by the model data structure. This can be tested if storage space problems are anticipated:

PK_BODY_ask_memory_usage returns the amount of memory currently occupied by a body’s data structures.

115.2.2 Tag bounds

You can manage the tag values in a session using the following functions:

Function	Description
PK_SESSION_set_tag_limit	Specify an upper bound range of Parasolid tag numbers to control the numerical range of tag values.
PK_SESSION_ask_tag_limit	Return the upper bound of Parasolid tag numbers.
PK_SESSION_ask_tag_highest	Confirm the maximum tag value currently being used in Parasolid.
PK_SESSION_ask_tags_remaining	Return the number of tags that are currently available for use.

Normally the tag limit is not expected to be changed during a Parasolid session. However, if it is changed, it is not affected by either session or partition roll operations - it remains at the value most recently set.

[back to top]

115.3 Session transmit (snapshot)

A session transmit file, or snapshot, is an image of a session at a particular instant, which can be loaded to re-create the session. Typically snapshots are used to:

Safeguard against losing data when a session stops unexpectedly. The user could make a snapshot at significant points in a session so that work done up to that point is not lost if the session stops unexpectedly.
Preserve data between sessions. The user can create a snapshot and stop a session, then resume work by restoring the snapshot.
Preserve the session so that faults can be re-created quickly and easily.

115.3.1 Saving a session

PK_SESSION_transmit and PK_SESSION_transmit_u are used to create a snapshot of a session. You can choose what format the file should be in using the transmit_format option. It has the following formats:

Format	Frustrum requirements
text	these three use the FFOPWR frustrum function
machine-dependent binary
machine-independent binary
neutral binary
“applio” (output via application-registered functions)	this format uses the application frustrum functions which are registered by PK_SESSION_register_applio_2

The chosen format should be provided in your application frustrum as required. For more information about using session files when reporting faults, see the Parasolid Fault Reporting manual.

You can also choose whether to save user fields, pmarks, session marks, and delta information, using the transmit_user_fields , transmit_deltas , and transmit_marks options respectively. See PK_SESSION_transmit_o_t for more information.

For further information about transmit formats see Chapter 2, “File Handling”, of the Parasolid Downward Interfaces manual.

115.3.2 Restoring a session

PK_SESSION_receive and PK_SESSION_receive_u restore a snapshot into the same version of Parasolid that transmitted it. For information on the options available in these functions, see PK_SESSION_receive_o_t.

Restoring a snapshot has the following effects on the session:

All the entities which previously existed in the session are deleted.
The new partitions and entities are the same as when the snapshot was saved.
If the snapshot was saved with the transmit_marks option set to PK_SESSION_xmt_marks_all_c, then all session marks (PK_MARK_t) are the same as when the snapshot was saved; otherwise no session marks are available.
If the snapshot was saved with transmit_deltas option set to PK_PARTITION_xmt_deltas_all_c, then all the pmarks in all partitions are the same as when the snapshot was saved; otherwise only the initial pmarks are available.
It is possible to roll back (using PK_MARK_goto_2) a restored snapshot to a previous state when that session was saved with session marks.

115.3.3 Session transmit version

PK_SESSION_receive_version and PK_SESSION_receive_version_u return information about the version of Parasolid used to create a session transmit file.

[back to top]

115.4 Journal files

A journal file is a record of all calls to Parasolid functions and the arguments returned from those calls. These files are intended as a debugging tool. A developer can inspect a journal file to identify faults in the application code (journal files are always stored in text format).

Performance issue: Journalling can be turned ON or OFF in a session. If the user or application may want to create a journal file at any stage, journalling must be enabled at the start of the session and switched OFF until required. This is important as journal files record a great deal of information and can become very large.

Control of journalling is provided by:

passing a filename to PK_SESSION_start - the file is opened and journalling starts
PK_SESSION_set_journalling to turn journalling on and off within a session
PK_SESSION_ask_journalling to enquire whether journalling is currently enabled

A PK function which returns an error to the application journals a comment describing the error code and its severity (except when the user error handler long-jumps over Parasolid).

The generation of journal files is described in Chapter 2, “File Handling”, of the Parasolid Downward Interfaces manual.

For an example of this functionality, see the code example in the C++\Code Examples\Application Support\Archiving\Journal Debug Report Session folder, located in example_applications in your Parasolid installation folder.

115.4.1 Adding a comment to a journal file

When journalling is on, PK_SESSION_comment can be used to assist deciphering files from the application. It enables a comment to be added to a journal file which can be used to link the PK function call to what the application was doing.

[back to top]

115.5 Recursion

The application’s GO functions are permitted to make calls to PK functions. This might be used, for example, to get data from an attribute attached to an entity being rendered. Only one level of recursion is allowed.

[back to top]

115.6 User fields

A user field consists of a number of bytes of memory, allocated to every entity in a session, in which data needed by the application can be stored. The data contained in the user field of each entity can be set and read individually, using PK_ENTITY_set_user_field and PK_ENTITY_ask_user_field.

The decision of whether to use user fields is fundamental to the architecture of the application. When deciding whether or not to use them compare the relative benefits of user fields and attributes:

User fields use memory space more efficiently because they have fewer overheads than attributes.
User fields are expensive if the part consists of many entities. If the data that is required to be stored is only relevant to one entity, then it would be cheaper on memory space to store the data as an attribute of that particular entity.
User fields are considerably faster than attributes.
User fields are of fixed length (16 bytes) and are attached to every entity in a session so are most attractive if data is to be attached to a large proportion of entities in a body.
When user fields are enabled, one user field is attached to each entity in the session. It is not possible to attach further user fields to entities.
Attributes can be created more selectively. Attributes have a definition which specifies the order and types of the data that the attribute can store. Many attribute definitions can be created, in addition to those created by the system.
Only one attribute of each definition can be attached to an entity (except for attributes of classes 6 and 7) and only certain classes of entity may own attributes; however within these constraints, any combination and number of attributes can be attached to an entity.
Attributes can be automatically propagated when the entities they are attached to are copied or split. A user field remains with the original entity (i.e. the entity with the original tag), and the user field of new entities so created is empty.
When loading saved parts into a session the application can choose not to load user fields saved with the part.
When loading saved parts with user fields, only user fields that are either the same length or shorter than the user fields in use can be loaded in the session. If no user fields are in use in a session, no user fields can be loaded with saved parts.
Attributes are always loaded with a saved part. If the part has attribute definitions that conflict with those in the session, the part cannot be loaded.

Users fields are enabled by passing the required length to PK_SESSION_start, and the current setting is returned by PK_SESSION_ask_user_field_len.

For further details of attributes see Chapter 95, “Attributes”.

[back to top]

115.7 Controlling memory allocation

When Parasolid requires memory for workspace or modelling operations, it calls the FMALLO function (PK_FMALLO_f_t) that you supply in the frustrum. Parasolid provides you with two functions that let you manage the minimum amount of contiguous space that Parasolid requests when it calls FMALLO. In some circumstances, changing the value of this minimum amount of memory may improve performance, both in terms of time and memory. For example, if your application’s memory management works on blocks of a certain size, using the same block size in Parasolid may improve performance slightly.

You can use PK_MEMORY_set_block_size to set the minimum memory that Parasolid requests via FMALLO. This function lets you specify a minimum block size between about 1/8 Mbyte (the default) and 16 Mbytes. It can be called at any time, whether or not the modeller is running. To return the minimum block size to Parasolid's default, call PK_MEMORY_set_block_size with an argument of zero.

You can use PK_MEMORY_ask_block_size to return the current minimum block size.

If you stop the modeller, the minimum block size is always reset to the default value.

Note: 1. Increasing the block size does not allow Parasolid to perform bigger modelling operations. Parasolid always requests the amount of memory it needs for a given job. Larger block sizes simply mean that fewer blocks are needed when passing memory to Parasolid, which in turn means that FMALLO and FMFREE are called less often.

Note: 2. The more you increase the minimum block size above the default, the less likely it is that Parasolid will be able to release blocks to the operating system after use. This may affect the performance of other processes on the system.

Note: 3. The exact limits of the block sizes you can set are platform-dependent. If you need to know these limits exactly, experiment by setting small and large values for PK_MEMORY_set_block_size and then using PK_MEMORY_ask_block_size to see what values are returned.

[back to top]

115.8 Managing the session settings when reporting errors involving multiple error entities

Sometimes, several entities are involved in a given error. In such cases, Parasolid lets you control, for the current session, whether additional information about these entities is returned in the Parasolid Report using the following functions:

Function	Description
PK_SESSION_ask_err_reports	Enquire whether additional error information is returned in a Parasolid Report of type PK_REPORT_4_t with the status PK_REPORT_4_error_report_c.Default: PK_ERROR_reports_off_c.
PK_SESSION_set_err_reports	Specify whether additional error information is returned in a Parasolid Report of type PK_REPORT_4_t with the status PK_REPORT_4_error_report_c.Default: PK_ERROR_reports_off_c.