Archives

Contents

• 100.1 Introduction
  • 100.1.1 Parasolid terminology
• 100.2 Transmitting a part
  • 100.2.1 Transmit format
  • 100.2.2 Transmit version - save as earlier version
  • 100.2.3 Transmitting indexed files
  • 100.2.4 Transmitting mesh data
  • 100.2.5 Contents of a part archive
  • 100.2.6 Identifiers
• 100.3 Receiving a part
  • 100.3.1 User fields
  • 100.3.2 Attributes
  • 100.3.3 Receiving specific faces from a part
  • 100.3.4 Receiving compound bodies in part files
  • 100.3.5 Receiving mesh data
  • 100.3.6 Receiving parts with mixed geometry
• 100.4 Transmitting a partition
  • 100.4.1 Transmitting partition history
  • 100.4.2 Contents of a partition archive
  • 100.4.3 Transmitting mesh data in a partition
• 100.5 Receiving a partition
  • 100.5.1 Receiving a partition’s pmarks and deltas
    • 100.5.1.1 Receiving mesh data and deltas in a partition

[back to top]

100.1 Introduction

Archiving is the process of saving the data in Parasolid’s internal memory to external storage. Your application can archive one or more parts, or the contents of a partition, into a single logical file or block of data.

Parasolid archives are intended to fit into whatever archiving system is used by your application. This could take the form of a controlled directory structure on the host computer, or some kind of database. The nature of this storage depends on your application’s frustrum.

Parasolid does not provide any means of deleting parts from archive, or listing keys which have been used to archive parts, either in the current session or in previous sessions. Your application must keep track of the keys used. Your application’s frustrum should also trap attempts to write new archive data to a place which already exists (i.e. re-use of keys).

See Chapter 2, “File Handling”, of the Parasolid Downward Interfaces manual for further information about the frustrum functions required to implement archiving.

See Chapter 22, “Assemblies And Instances”, for further information on the use of assemblies in archiving.

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

100.1.1 Parasolid terminology

To save or write data from Parasolid to an external store is referred to as transmitting information.

To load or read data from an external source into the current Parasolid session is referred to as receiving information.

[back to top]

100.2 Transmitting a part

PK_PART_transmit and PK_PART_transmit_u transmit one or more parts to a logical block of data through the frustrum. You supply these functions with a key string which the frustrum can use, for example, as a filename or an index into a database.

• If the key string includes Unicode characters, use PK_PART_transmit_u. If the key string does not include Unicode characters, use PK_PART_transmit.
• Your application is responsible for storing the key string so that the part can be retrieved in a later session.

In addition, you can use PK_PART_transmit_b to transmit one or more parts to application memory.

For all three of transmit functions:

• The parts need not all be in the same partition.
• A part is a body or assembly - subordinate entities, like edges and surfaces, cannot be saved on their own.

100.2.1 Transmit format

There are five formats that can be used for the archive, which should be provided in your application’s frustrum as required.

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

100.2.2 Transmit version - save as earlier version

A part may be transmitted so that it can be received by a version of Parasolid earlier than the current version (the version doing the transmitting).

This means that parts modeled in the current version of Parasolid can also be archived in any format from V7 onward, and thereafter received by an application using that earlier version of Parasolid.

You use the transmit_version option in PK_PART_transmit_o_t to specify the version you want to use.

Parasolid provides two methods for supporting backwards compatibility in XT data:

100.2.3 Transmitting indexed files

When you transmit one or more parts, you can opt to transmit the files using a format that allows specific faces to be received by subsequent Parasolid sessions, rather than an entire part. This is particularly useful if you are transmitting large parts with the expectation that users will only need access to certain information from those parts during future editing sessions.

In order to transmit files with the required indexing information, you need to do a number of things:

• You need to register a special indexed frustrum, rather than the standard Parasolid frustrum. You do this by calling PK_SESSION_register_indexio rather than PK_SESSION_register_frustrum.
• When transmitting parts using any of the transmit functions, you need to set transmit_format to PK_transmit_format_indexio_c.
• When transmitting parts using any of the transmit functions, you need to use the transmit_indexed_context option to supply a pointer to indexing data stored by your application. The context is a way for your application to communicate with the functions defined in the indexed frustrum.

Once you have transmitted a part as an indexed file, you can still receive the whole part into a Parasolid session as normal; the only difference is that an indexed part file is slightly larger than a non-indexed part file, and a number of received nodes will be deleted immediately after receiving the part.

Section 100.3.3, “Receiving specific faces from a part”, describes how you can receive a specific face from a part that has been transmitted with indexing information.

100.2.4 Transmitting mesh data

You can transmit mesh data to separate files or embed the data within the part file using the transmit_meshes option. The transmit_meshes option has the following values:

When the transmit_meshes option is set to PK_transmit_meshes_embedded_c:

• all mesh data is stored within the part file
• data for each mesh can be optimally accessed using the receive_using_seek option in PK_PART_receive. See Section 100.3.5, “Receiving mesh data” for more information.
• the transmit_format option must be one of the binary formats and the frustrum seek function FFSKXT must be registered using PK_SESSION_register_fru_2.

100.2.5 Contents of a part archive

When a part is archived, the following items are saved:

• All topological and geometric entities contained in the part.
• The user field of each entity (optional).
• Identifiers (of all entities which have them).
• Any groups belonging to the part.
• Any attributes belonging to entities in the part.
• Any construction geometry attached to the part (as returned by PK_PART_ask_geoms).If the part is an assembly, all sub-assemblies (down to bodies at the bottom level) are saved with it.

And optionally, in a separate place:

• All mesh data is stored in a separate file. See Section 100.2.4, “Transmitting mesh data”, for more information.

100.2.6 Identifiers

Identifiers are integer values which are attached to all entities within a part, except for fins and the part itself. The identifiers within a part are distinct. Unlike tags, they are saved when a part is archived, so identifiers can be stored with a part key in an external database to keep a handle on a particular entity.

See Section 2.4.4, “Identifiers”, for more general information about identifiers.

There is no guarantee that the same entities have the same tags when loaded into another session. The decision as to whether your application should use identifiers depends upon whether it needs to reference specific entities within archived parts in different modeling sessions.

If you do need to use identifiers, then it is important that you record the identifiers for all entities that you may wish to access in a new session, prior to transmitting the part. You do this by calling PK_ENTITY_ask_identifier for each entity that you are interested in.

When receiving the part in a new session, you need to find the tags of those entities whose identifiers you previously recorded. Do this by calling PK_PART_find_entity_by_ident for all of your recorded identifiers.

Naturally, you need to save the list of saved identifiers between sessions, independently of the part itself.

The following table summarizes the differences between identifiers and tags with respect to archiving and Parasolid sessions:

* caution must be applied as a change of tag could appear to occur when an entity is replaced by a similar entity

[back to top]

100.3 Receiving a part

PK_PART_receive and PK_PART_receive_u receive one or more parts from a logical file or data block through the frustrum, using the key string given by the application.

• If the key string includes Unicode characters, use PK_PART_receive_u. If the key string does not include Unicode characters, use PK_PART_receive.

It is your application’s responsibility to ensure that Parasolid can find the archive data for the part. This is mostly dependent on the frustrum. If the key cannot be found by the frustrum (for instance because it simply treats keys as filenames and has no information on which directory to look in) then PK_PART_receive and PK_PART_receive_u fail.

In addition, you can use PK_PART_receive_b to receive one or more parts from application memory, provided these parts have been transmitted in the same, or an earlier, version of Parasolid. You can use PK_PART_receive_version, PK_PART_receive_version_b, or PK_PART_receive_version_u to obtain the version of Parasolid used to create part transmit data.

For all three receive functions:

• The parts are created in the current partition.
• Multiple parts are restored in the same order as they were transmitted.

Parts are transmitted with a reference to a specific Parasolid schema file. Once you have updated the version of Parasolid used by your application, its frustrum must retain schema files for each version used, or else your application is unable to receive old parts. You can find out what the current schema version is using PK_SESSION_ask_schema_version.

100.3.1 User fields

To receive user fields archived with the entities of a part, the length of the archived user fields must be the same as, or shorter than, that set for the current session by PK_SESSION_start.

If they are not, you can prevent PK_PART_receive and PK_PART_receive_u from trying to read them by setting the receive_user_fields option to false. This makes Parasolid do the following:

• Ignore the user fields which were saved with the part.
• Create user fields of the length required by the current session.
• Set these user fields to zero.

For further information see the “User fields” section in Chapter 115, “Session Support”.

100.3.2 Attributes

If a part has user-defined attributes attached, the attributes and their definitions are transmitted with the part. When the part is then received into a session, the kernel automatically loads the attribute definition of the attributes, if there is no definition with the same name already in the session.

If the attribute definition already exists in the new session, and matches the definition saved with the part, the part can be retrieved.

If the attribute definition already exists in the new session, but does not match the definition saved with the part, you can use the attdef_mismatch option to control the behaviour. This option takes the following values:

100.3.3 Receiving specific faces from a part

If a part has been previously transmitted with indexing information (as described in Section 100.2.3, “Transmitting indexed files”), then you can opt to receive specific face from the part, rather than the whole part. This can be particularly useful if the part file is very large, and you are only interested in working with some of the information it contains.

To do this, you need to specify the following options when receiving the part. These are all available in the PK_PART_receive_o_t options structure:

transmit_format

part_index

n_identifiers

identifiers

receive_indexed_context

In addition, you can optionally use key_is_partition to receive a specific face from a part stored in partition data. If this option is PK_LOGICAL_true, then the specified key is assumed to contain partition data (created as described in Section 100.4, “Transmitting a partition”). In this case, the ordering of the bodies used to define part_index is the same as that returned by PK_PARTITION_ask_bodies.

100.3.4 Receiving compound bodies in part files

You can receive compound bodies into a session by using any of the standard receive functions: PK_PART_receive, PK_PART_receive_u, or PK_PART_receive_b. See Section 15.12.1.4, “Receiving compound bodies into a session”.

100.3.5 Receiving mesh data

How mesh data is received into a session depends on whether it is embedded in the XT file or is in a separate XMM file, and can be controlled using the receive_using_seek option. This takes the following values:

When the transmit_meshes option is set to PK_transmit_meshes_embedded_c:

When the transmit_meshes option is set to PK_transmit_meshes_separate_c the mesh data is in a separate XMM file therefore the receive_using_seek option has no effect and mesh data will be loaded into the session when it is needed.

If you wish to optimise the receive_using_seek option, you need to register the frustrum seek function FFSKXT using PK_SESSION_register_fru_2. See Section 5.3, “Registered frustrum” in the Downward Interfaces manual for more information.

100.3.6 Receiving parts with mixed geometry

The receive_mixed option allows you to control whether to receive parts containing a mixture of classic and facet geometry in your application. On receiving data into a Parasolid session, you can choose to set receive_mixed to one of the following values:

[back to top]

100.4 Transmitting a partition

PK_PARTITION_transmit and PK_PARTITION_transmit_u transmit a partition as a logical block of data through the frustrum. PK_PARTITION_transmit_b transmits a partition to application memory. As for part data:

• The transmit format may be text, machine-dependent binary, machine-independent binary, neutral binary, applio (calls application-registered functions), or indexed (calls application-registered indexing functions). See Section 100.2.1, “Transmit format”, for details.
• You can specify a transmit_version so that the partition can be received by previous versions of Parasolid. In order to transmit partitions, the value of transmit_version must be at least 120. See Section 100.2.2, “Transmit version - save as earlier version”, for details.
• You can specify indexing information using transmit_indexed_context , so that specific faces from the partition data can be received by another Parasolid session. See Section 100.2.3, “Transmitting indexed files”, for details. To receive such data, see Section 100.3.3, “Receiving specific faces from a part”.

100.4.1 Transmitting partition history

By default, PK_PARTITION_transmit transmits the current state of a given partition. If required, you can transmit the history of the partition as well, in terms of its pmarks and delta information. You use the transmit_deltas and pmarks options to do this:

• transmit_deltas provides basic control for transmitting the partition history.
• pmarks provides additional control, allowing you to transmit specific segments of the partition history, while omitting others.

The transmit_deltas option takes the following values:

Figure 100-1 Transmitting pmarks in the main line

If you use transmit_deltas , then:

• The partition must be at a non-initial pmark.
• The pmarks and deltas are written to a separate place, with the same key - the existing delta data is opened, read and output to the new transmit data.
• PK_PMARK_ask_identifier returns the identifiers of pmarks so their new tags can be obtained when they are retrieved into a new session.

The pmarks option lets you override the deltas to transmit, by providing a specific set of pmarks. The way these pmarks are interpreted depends on the setting of transmit_deltas :

When transmitting specific pmarks using this option, pmarks are transmitted on the fly without affecting the current session, and the deltas are merged and relinked in the transmitted data.

In Figure 100-2, if you do not want to transmit P5, then the junction pmark P4 is not required. However, if you want to transmit P5 , then junction pmark P4 is required. In both cases, P1 and P6 also need to be transmitted, because they are the initial and current pmarks.

Figure 100-2 Transmitting junction pmarks

100.4.2 Contents of a partition archive

When a partition is archived, the following items are saved:

• All parts in the partition
• Any orphan geometry attached to the partition

and optionally:

• All user fields in the partition
• All attribute definitions in the session (or just those used in the partition)

and optionally, in a separate place:

• All pmarks and deltas in the partitions, or
• Just those pmarks and deltas in the “main line”
• All mesh data is stored in a separate file. See Section 100.2.4, “Transmitting mesh data”, for more information.

If the transmit_all_attdefs option is left at the default value of PK_LOGICAL_true, then all attribute definitions available in the Parasolid session are transmitted. If you set transmit_all_attdefs to PK_LOGICAL_false then only those attribute definitions that are actually used in the partition are transmitted. In order to minimise the size of partition files, you are advised to set transmit_all_attdefs to PK_LOGICAL_false.

100.4.3 Transmitting mesh data in a partition

You can transmit mesh data into a separate file or embed it within the partition file using the transmit_meshes option as described in Section 100.2.4, “Transmitting mesh data”.

[back to top]

100.5 Receiving a partition

PK_PARTITION_receive and PK_PARTITION_receive_u receive a partition from a logical file through the frustrum. PK_PARTITION_receive_b receives a partition from application memory.

• A new partition is created (the current partition is not changed).
• The contents of the partition are in the same order (as returned by various enquiry functions) as when it was transmitted, so that the application can relate the received entities to the transmitted ones.
• The functions PK_PARTITION_receive_version, PK_PARTITION_receive_version_u, and PK_PARTITION_receive_version_b return information about the Parasolid version used for the received partition.
• If build_number is 0, the partition was originally transmitted using the transmit_version option. The version number returned represents the format used for the transmit file, rather than the version of Parasolid used to create it. See Section 100.4.
• If build_number is non-zero, the version number returned represents the actual version of Parasolid used to create the transmit file.

You can specify a number of options when receiving partitions, including the following:

receive_deltas

receive_all_attdefs

attdef_callback

attdef_callback_on

attdef_context

allow_missing_deltas

receive_using_seek

receive_compound

receive_mixed

100.5.1 Receiving a partition’s pmarks and deltas

PK_PARTITION_receive_deltas_2 receives the pmark graph and deltas for a given partition from a logical file through the frustrum:

• The key, transmit format and user-field options used are assumed to be the same as the call to PK_PARTITION_receive or PK_PARTITION_receive_u which received the given partition.
• The deltas must have been transmitted in the same version of Parasolid, unless the option receive_prev_version_deltas was given to PK_PARTITION_receive or PK_PARTITION_receive_u, in which case deltas transmitted from earlier compatible releases of Parasolid may be receivable. Note that transmission of deltas from previous versions is not always guaranteed. See Section 100.4.2, “Contents of a partition archive”, for details.
• The pmarks may have different tag values to when they were transmitted - their identifiers should be used to identify them.

Deltas can only be received for a partition if that partition was received earlier in the session, with option PK_PARTITION_rcv_deltas_later_c, and the pmark which the partition was at immediately after being received, has not been deleted. However, the partition may be modified, and pmarks created, between receiving the partition and receiving its deltas. This is illustrated in Figure 100-3 (current pmarks are shown in blue).

Figure 100-3 Pmark graph as transmitted

If you use session marks (see Section 97.4, “Session rollback”, for more information) and session roll forward is switched off, you can use the new_at_mark option in PK_PARTITION_receive_deltas_o_t to manage correct deletion of pmarks received via deltas when rolling the session back to a previous mark.

By default, when you receive pmarks into a partition via deltas, the “age” of those pmarks is denoted by the point at which the delta was received into the partition, even though the partition itself was received earlier. Pmarks received via deltas in this way are deleted when rolling the session back to a point before the delta was received, even if the partition itself had already been received at that point.

In order to avoid this, set new_at_mark to PK_PMARK_new_with_partition_c. This ensures that pmarks received via deltas are not deleted when rolling the session back to a point before the delta was received: any pmarks received via deltas are only deleted if the session is rolled far enough back that their owning partition no longer exists. Figure 100-4 shows a simple example of this in use (current pmarks are shown in blue).

Figure 100-4 Controlling deletion of pmarks when rolling the session back

100.5.1.1 Receiving mesh data and deltas in a partition

Parasolid’s meshes are optimised not to load their mesh data until it is needed for an operation (i.e. the meshes are lazily loaded).

However, if the partition received (via PK_PARTITION_receive) contains mesh data and the receive_deltas option is set to either PK_PARTITION_rcv_deltas_yes_c or PK_PARTITION_rcv_deltas_later_c, Parasolid will load all of the meshes in that partition immediately. Any subsequent calls to the PK_PARTITION_receive_meshes function have no effect. If you are using PK_PARTITION_receive and you want to load meshes lazily, the receive_deltas option must be set to PK_PARTITION_rcv_deltas_no_c.

Furthermore, if a pmark is created in a partition, Parasolid will load all meshes into the session that have not previously been loaded. Therefore you need to ensure your frustrum is capable of handling multiple calls to the relevant frustrum functions when loading a partition (or part) that contains mesh data. See Section 5.3, “Registered frustrum” in the Downward Interfaces manual for more information.

[back to top]