Mapping (MAP) Subsystem

The MAP subsystem provides a framework for creating single and multi-schema PDElib applications. The framework allows an application to access much of the functionality in PDElib with a single, consistent interface by encapsulating entity operations into discrete modules called mapping functions. These mapping functions are similar to methods in an object oriented language. This subsystem provides functions for defining, maintaining, and using mapping functions.

This manual page is organized so that all of the basic concepts are presented first followed by a summary of how the concepts are put together. A set of advanced topics appears at the end.

The following terms are used throughout the MAP subsystem:

Components

There are seven interrelated components which work together to form the MAP subsystem framework. These components are:

These components are recursively invoked until the desired result is obtained as shown below:

   map_DispatchEntity ()
      mapping_function ()
         map_ProcessEntity ()
            map_DispatchEntity ()
               mapping_function ()
                  .
                     .
                        .

An application can also provide a dispatcher which is inserted into the call chain. map_IsCommitMapping can then be used to determine when mappings are finished. These topics are discussed further in the USING AN APPLICATION DISPATCHER section.

map_InvokeMapping is only utilized for invoking components of conditional mapping definitions. This is an advanced topic and thus more information may be found in the ADVANCED TOPICS section.

To demonstrate how this recursive processing works, the following example shows the call order for converting an IGES NURB to a STEP NURB. This conversion is performed using two mapping steps:

   IGES NURB -> GDX NURB
   GDX NURB -> STEP NURB

The following call tree uses symbolic names for the mapping functions to make it obvious what part of the mapping they are performing. All arguments are input parameters.

   map_DispatchEntity (IGES NURB)
      IGES_NURB_To_GDX_NURB (IGES NURB)  <- Mapping function
         map_ProcessEntity (GDX NURB)
            map_DispatchEntity (GDX NURB)
               GDX_NURB_To_STEP_NURB (GDX NURB)  <- Mapping function
                  map_ProcessEntity (STEP NURB)  <- End of mapping

The map_ProcessEntity function uses several factors to determine when an entity mapping is complete. The simplest of these is a flag associated with the mapping which indicates that the result of the mapping is to be committed. In this case, the application would set this flag on the "GDX NURB -> STEP NURB" mapping. If an application dispatcher is involved in the processing, it can stop the mapping at any invocation. This is described further in the USING AN APPLICATION DISPATCHER section. Additionally, the mapping function itself can be defined so that it does not call map_ProcessEntity. This is described further in the MAPPING FUNCTIONS section.

As described above, the entity generated in the final mapping step is made permanent (the STEP NURB in this case). All other entities generated in mapping functions are transient entities which are automatically deleted by map_ProcessEntity when returning back up the call stack. In this example, the GDX NURB is a transient entity. In this example, the top level entity (the IGES NURB) is defined in a PDElib model. The MAP subsystem is based on applying mapping functions to entities which are defined in PDElib models. By incorporating an application dispatcher to handle native to/from PDElib conversions, the MAP subsystem can be used to access and map native entities. This is described further in the INCORPORATING NON-PDELIB BASED ENTITIES.

The MAP subsystem makes use of the MDA original database pointer field in each entity to maintain a link back to the entity it was created from. In this example, the original database pointer of the STEP NURB would be set to the database pointer of the IGES NURB. This allows attributes or other information not mapped by the mapping functions to be maintained in the final entity. See the mda_intro manual page for additional information on using original database pointers.

There are three types of mapping functions supported by the MAP subsystem. The two main types that will be encountered most often, the "End Mapping" and "General Mapping", will be discussed in this section. The third type, the "Conditional Mapping", will be described in the advanced topics section later in this document. The type is specified as part of the option argument when the mapping is defined. By default, the mapping is defined to be an "End Mapping". If the MAP_GENERAL flag is specified, the mapping is a "General Mapping". These two types are described below:

In order for the MAP subsystem to use mapping functions without any knowledge of what a particular mapping function does, each mapping function must have the following binding.

The first argument is the database pointer of the entity to be mapped. The mapping function must not modify this entity in any way. The second argument is a structure containing information about the mapping. The contents of this structure is describe in the MAP_INFO section.

This section describes the requirements for general mapping functions only (those defined with the MAP_GENERAL option). The only requirements for end mappings are that they do not call map_ProcessEntity.

Code Structure

While there are no limitations on the type of processing performed by a mapping function, it must ensure that the following steps are carried out:

The following code fragment shows a typical mapping function skeleton for a mapping defined with the MAP_TRANSIENT option:

   PDX_MSGT mapping_function ( MDA_PTR db_ptr, MAP_INFO *info )
   {
      ... Generate new entity in the model info->model
      /*  Assign original database pointer field  */
      mda_SetOrigDbptr ( MDA_NOOPT, new_ent, mda_GetOrigDbptr(old_ent) );
      /*  Pass entity back in for further processing  */
      rc = map_ProcessEntity ( MAP_NOOPT, new_db_ptr, info );
   }

Additional Guidelines

Other caveats which should be observed when developing mapping functions are listed below. These guidelines are required when developing mapping functions that generate PDElib entities which are passed to map_ProcessEntity.

Simple Mappings

A simple mapping definition consists of a symbolic mapping name, the mapping function which performs the mapping, the DTF of the entity type which the mapping is to be applied to, and the DTF of the entity or entities which the mapping generates. There is also a flag associated with the mapping which specifies if the mapping can be chained together with other mappings to form a complex mapping definition (called a mapping list). In order for a mapping to be chainable, it must only generate a single DTF as output. It can generate multiple entities, but they must all have the same DTF.

Mapping Lists

A mapping list consists of a set of simple mappings and/or mapping lists which are to be applied in a sequence and treated as if they were a single mapping. This allows complex mappings to be created by chaining other mappings together. If the last simple mapping or mapping list in the sequence is flagged as being chainable, then the new mapping is also chainable. The mapping list can be treated much like a simple mapping. The DTF that the mapping list expects for input will be the same the DTF for the first mapping in the sequence.

Mapping tables define what mapping function(s) should be applied to each DTF encountered. Mapping tables are declared with the MAP_TABLE data type. Each mapping table contains a tree of mapping definitions and a tree of enabled mappings. By having these two trees, a single table may contain a variety of mappings, of which only a few are actually enabled. This allows PDElib to define all of the supported mapping functions in a single step. The application or end user can then selectively enable the mappings that they want to have applied. Mapping tables are created using the map_CreateTable function.

Mappings must be defined before they can be used. To add pre-defined PDElib mappings to a mapping table, the application must call a PDElib interface specific function which defines the mappings for that particular interface. The name of this function will be xmap_DefineMappings where x is the interface prefix letter. The function gmp_DefineMappings can be used to define the GDX mappings.

Application mappings are defined using the function map_DefineMapping. This function takes a mapping name, mapping function, the DTF that the mapping expects as input, and the DTF of the output entity. Mapping lists can be defined using the function map_DefineMappingList. This function takes a mapping name and a list of previously defined mappings and/or mapping lists.

See the USING MAPPING DEFINITION FILES section for information on an alternative approach to calling map_DefineMapping.

Once a mapping or mapping list has been defined, it must be enabled before the MAP subsystem will apply it. The function map_EnableMapping is used for this. In addition to specifying the mapping to be enabled, an application can specify the following items:

These items are described in detail in the map_EnableMapping manual page.

The MAP subsystem allows optional parameters to be passed to mapping functions through the use of a name/value interface. This allows parameters (such as tolerance) to be specified differently for each mapping that is enabled.

A parameter is defined by specifying a name, type, default variable, and default value to the function map_DefineParameter. The default value can then be overridden for this parameter when the mapping is enabled using map_EnableMapping (see the map_EnableMapping manual page for details on the syntax to do this). Mapping parameters are global to all mapping tables.

Parameter names are represented using #defines for efficiency. In order to avoid duplication of #defines, the parameter name is placed in a .msg file which is compiled with the message table compiler (see the mtc manual page).

Mapping parameters can be defined as being one of the following data types:

Defining New Mapping Parameters

Note that these steps are only needed to create new parameters. To use PDElib defined parameters, skip to the next section.

The default values for parameters are stored in global variables maintained by the application. This is done to minimize the overhead of retrieving parameters in the mapping functions. By registering the address of the global variable containing the default value for a parameter, the function map_SetParameterDefault can be used to modify default values.

The steps involved to add an application defined mapping parameter are shown below. This example shows how to add parameters named ASYS_PROC_METHOD, ASYS_CONVERT_TO_NURBS, and ASYS_TOL with types MAP_DEFINE, MAP_BOOLEAN, and MAP_DOUBLE respectfully. It assumes that an application subsystem called ASYS, and its associated message file "asys.msg", have already been created.

   PROC_METHOD "";
   CONVERT_TO_NURBS "";
   TOL "";

   MODEL_MODE "";
   DRAW_MODE "";

   extern PDX_MSGT asys_proc_method;
   extern int asys_convert_to_nurbs;
   extern double asys_tol;

   map_DefineParameter ( MAP_NOOPT, ASYS_PROC_METHOD, MAP_DEFINE,
                         &asys_proc_method, ASYS_MODEL_MODE );
   map_DefineParameter ( MAP_NOOPT, ASYS_CONVERT_TO_NURBS, MAP_BOOLEAN,
                         &asys_convert_to_nurbs, PDX_FALSE );
   map_DefineParameter ( MAP_NOOPT, ASYS_TOL, MAP_DOUBLE, &asys_tol, 0.01 );

The parameters can now be used in mapping functions as described in the next several sections.

Setting Mapping Parameter Defaults

The default value for a parameter can be set using the function map_SetParameterDefault. This value will then be used whenever a parameter is not explicitly specified to map_EnableMapping. To change the default value for the ASYS_TOL parameter, the following call would be made:

   map_SetParameterDefault ( MAP_NOOPT, ASYS_TOL, .1 );

Note that this is equivalent to setting the asys_tol global to .1. Using the map_SetParameterDefault function provides a consistent way to set both application and PDElib defined parameter defaults.

Setting Mapping Parameters

The values for mapping parameters are specified when mappings are enabled using map_EnableMapping. They are specified using the MAP_PARAM token in the variable argument list. The map_EnableMapping manual page describes the syntax used. The following example shows a mapping being enabled with all three of the parameters defined in the previous section.

   map_EnableMapping ( MAP_NOOPT, table, "application mapping",
                       MAP_PARAM, ASYS_PROC_METHOD, ASYS_MODEL_MODE,
                       MAP_PARAM, ASYS_CONVERT_TO_NURBS, PDX_TRUE,
                       MAP_PARAM, ASYS_TOL, .1,
                       MAP_END );

Using Parameters In Mapping Functions

Mapping functions access parameter values using the function map_GetParameter. This function takes a mapping name and a parameter name, and returns the corresponding value. If the parameter was not specified when the mapping was enabled, a return code of MAP_NO_VALUE will be returned.

The following code shows how to retrieve the ASYS_TOL parameter:

   double tol = asys_tol;

The MAP_INFO structure contains information which is passed from one mapping to the next through map_DispatchEntity, map_ProcessEntity, map_CommitEntity, and the application dispatcher. This structure is also used by the application to specify certain parameters which are to be used in the mapping process including the mapping table, the application dispatcher function, and an OLM list to store the results of the mapping process in. The function map_InitMapInfo initializes a MAP_INFO structure with default values. The application can then override certain values.

The actual structure declaration is shown below followed by a detailed description of each field. Unless noted otherwise, a field can only be modified by the application before calling map_DispatchEntity or map_DispatchList (i.e. they can not be modified in a mapping function called under map_DispatchEntity). For the fields which the application can change at any time, a change will only be visible at the current recursion level and deeper because map_DispatchEntity duplicates the MAP_INFO structure at each recursion level.

typedef struct {

Contains bit flags to control certain characteristics of the mapping process. Multiple options can be specified by or'ing together multiple bit masks. The valid options are:

data

A void pointer which the application can use to pass information through the MAP subsystem. This field is ignored by the MAP subsystem and can be modified at any time by the application.

depth (Read Only)

The current depth of recursion in map_DispatchEntity. At the top level (before map_DispatchEntity has been called), the depth will be 0. The depth is incremented at each recursive invocation of map_DispatchEntity.

model (Read Only)

Used to tell mapping functions what model the resulting entities should be created in. map_DispatchEntity will set this field based on the following rules:

table

The mapping table containing the mappings to be applied. This field must be set by the application before invoking map_DispatchList or map_DispatchEntity. The table is created using map_CreateTable.

mapping (Read Only)

The mapping which is currently being applied. This field is only valid inside of mapping functions. Mapping functions need to pass this field into map_GetParameter to obtain mapping parameters. Mapping functions should not access the structure referenced by this field except to obtain the mapping name (stored in mapping->hdr->name as a char * string).

dispatcher

Specifies an application dispatcher to be called from map_ProcessEntity. See the USING AN APPLICATION DISPATCHER section for additional information.

stack

Used to track attributes through a mapping. Only used for interfaces which make use of the EAM subsystem.

list

Specifies an OLM list to add subsequently created entities to. This allows an application to capture the list of entities created by subsequent recursive processing. If this field is not NULL, map_ProcessEntity and/or map_CommitEntity will add the database pointer of each committed entity to the list (note that only the database pointer passed to map_ProcessEntity will be added, subordinate pointers will not be). The application can change this field at any time to have multiple lists active. The application is responsible for allocating and freeing any lists. The list should be allocated with a call similar to:

   info.list = olm_CreateList ( OLM_NOOPT, sizeof(MDA_PTR), 50, NULL );

Application mapping functions can add additional entities to the list if needed.

_ps

This structure contains processing information maintained by the MAP subsystem and should not be accessed by application code.

This section summarizes the steps required to use the MAP subsystem.

The MAP subsystem provides a simple external file interface which allows the following to be controlled from an ASCII file:

The function map_LoadMapFile is used to process the entries in the external file. See the map_LoadMapFile manual page for the file format and additional information.

If an application needs more control over the mapping process than what the map_DispatchEntity/mapping function/map_ProcessEntity sequence provides, it can specify a function to be inserted into the call sequence prior to map_DispatchEntity on each entity. Application dispatchers are used primarily for the following purposes:

To use an application dispatcher, the info->dispatcher field in the MAP_INFO structure is set to the address of the dispatcher function. The application dispatcher has the same argument list as a mapping function. map_ProcessEntity will invoke then application dispatcher rather than map_DispatchEntity.

Regular mapping functions expect a specific type of entity as input. However, some mapping type operations can be performed on any entity regardless of its DTF. These are called generic mappings. The MAP subsystem currently supports only a single type of generic mapping which copies an entity. This is useful for applications which map entities from an input model to an output model but may want to just copy certain entity types. Generic mappings are enabled just like a regular mapping. The mapping names used for generic mappings are based on the entity name and the type of generic mapping. For example, the generic mapping to copy an entity named "gdx_nurb_curve" would be "gdx_nurb_curve copy". The following table shows the types of generic mappings and their corresponding names:

Generic mappings can not be used as part of a mapping list.

The remaining sections describe the more advanced functionality available within the MAP subsystem.

Chainable mappings have a refined set of rules when considering the scope of mapping lists and conditionals. These rules are as follows:

Conditional mappings may be defined by calling map_DefineConditionalMapping. A conditional mapping definition consists of a symbolic mapping name, the mapping function that will select one of the defined component mappings, the DDF and TF of the entity type which the mapping is to be applied to, and a set of possible component mappings. Like mapping lists, conditional mappings are treated in a manner very similar to a single mapping. It is possible to define mapping lists as well as other conditional mappings as components of a conditional mapping as long as all rules for chaining mappings are followed. Likewise, conditional mappings may appear within mapping lists. All component mapping operations of a conditional mapping must be defined before they are included in a conditional definition.

For example, a conditional mapping could be set up to convert gdx_nurb_curve(s) to either gdx_arc(s) or gdx_polyline(s) based on a tolerance.

The conditional mapping could be defined with a call to map_DefineConditionalMapping as follows:

   map_DefineConditionalMapping ( MAP_NOOPT, table,
                                 "gdx_nurb_curve -> gdx_arc or gdx_polyline",
                                 ddf, tf, mapping_function,
                                 "gdx_nurb_curve -> gdx_arc",
                                 "gdx_nurb_curve -> gdx_polyline" );

Once a conditional mapping has been defined, it must be enabled before the MAP subsystem will apply it. The function map_EnableMapping is used for this purpose. Parameters specified to map_EnableMapping in association with a conditional mapping will be copied down into each component. Thus there is no method for distinctly specifying independent parameters for each component.

The function, map_InvokeMapping, is used to invoke a selected component of a conditional mapping. It should be called from the function associated with the named conditional. map_ProcessEntity should never be called from the conditional function.

For the above example, the function could look like:

   PDX_MSGT mapping_function ( MDA_PTR db_ptr, MAP_INFO *info )
   {
      
      /* Get parameters associated with mapping */
      
      ...
      
      /* Select a mapping based on the parameters */
      
      if ( operation & arc ) 
      {
         map_InvokeMapping ( "gdx_nurb_curve -> gdx_arc", db_ptr, info );
      }
      else
      {
         map_InvokeMapping ( "gdx_nurb_curve -> gdx_polyline", db_ptr, info );
      }
   }

The functions map_DefineMappingList and map_EnableMapping support a string based interface which allows the variable argument lists to be specified with a character string rather than a combination of #define values. This allows the MAP subsystem to be configured at run-time. See the map_DefineMappingList and map_EnableMapping man pages for additional information.

Special circumstances sometimes exist that require a slightly modified approach to the standard mapping function algorithm. When processing a structure type of entity, such as an IGES group, it may be best to construct the mapping function in a two tiered approach. This approach will work best for entities that must be mapped by processing their subordinates first and then reformulating these into a new structure entity. The most notable difference between this methodology and the standard algorithm explained in the WRITING MAPPING FUNCTIONS section is that map_DispatchEntity is called from within the mapping function instead of map_ProcessEntity. The following steps outline the key points of structure processing:

For more insight on this topic, review the apls_GroupToIGES402.c sample function included in the apls_out sample program.

When a mapping is defined, the DTF that it operates on is specified as an argument to map_DefineMapping. In some cases, the same mapping function will operate on several different forms of the same entity. The MAP subsystem allows wildcarding the form portion of a DTF so that a mapping function will be associated with every form of the entity. The resulting mapping definition behaves the same as a regular mapping definition but applies to all forms of the entity. The form is wildcarded by specifying DDF_ANY_FORM for the form in DTF. See the map_DefineMapping manual page for additional information.

The MAP subsystem allows multiple mappings to be enabled for a DTF. The order in which they are enabled determines the order that they will be applied. This allows mappings to output the same type of entity as was input. The MAP subsystem prevents infinite loops by keeping track of what mappings have already been applied to a given entity. If an application dispatcher is used in conjunction with multiple mappings for a DTF, the dispatcher will only be called with the results of the last enabled mapping. Normally all the mappings except the last should generate the same DTF as the input. If an intermediate mapping generates a different DTF, it will be dispatched according to the first mapping enabled for the new DTF. If an application dispatcher is defined, it will not be called until the last mapping for the new DTF is processed.

The resulting database pointer(s) from a mapping can optionally be stored in an OLM list. To do this, the application allocates an OLM list (see the olm_CreateList manual page) and stores the resulting OLM_LIST pointer in the "list" field of the MAP_INFO structure. The final entities created from any subsequent mappings will be appended to this list. The list can be temporarily or permanently disabled by setting this field to NULL. Mapped entities are automatically added to the list by map_ProcessEntity when the entity is committed. Mapping functions may write other entities to the list if needed. See the MAP_INFO section for additional information.

A mapping definition file (MDF) provides a method for defining and documenting mappings in a single file. A utility called mdc takes an MDF file and generates either C code for defining mappings or a manual page describing the available mappings. See the mdc manual page for additional information.

Several debugging functions are provided with the MAP subsystem. A summary of these appears in the following table. The map_DbgSetTracing function can be particularly useful in diagnosing problem mappings. Note that on some systems these can be called interactively from the system debugger. See the appropriate manual page for usage information.

Although the map subsystem can be used in its entirety without knowledge of the specifics of its inner workings, there are times when it may be helpful to know what goes on inside the black box. This section describes the mechanics of map_DispatchEntity, map_ProcessEntity, and map_CommitEntity.

map_ProcessEntity

map_ProcessEntity will process the entities generated by mapping functions. If an application dispatcher is defined, it will always be invoked on the entity. If no application dispatcher is used, the entity will either be committed (if info->mapping was enabled with MAP_COMMIT) or sent back into map_DispatchEntity otherwise. Entities that do not get committed are recursively deleted. The following pseudocode demonstrates:

   Get DTF of entity
   if (current mappings target dtf != DTF of entity)
      Issue error message and return
      
   if (application dispatcher is not defined)
      if (current mapping enabled with MAP_COMMIT)
         Commit entity (map_CommitEntity)
      else
         Dispatch on entity (map_DispatchEntity)
	 
   else /* Application dispatcher is defined */
      Invoke application dispatcher on entity
      
   if (entity not flagged as committed and
       MAP_NO_DELETE option not set)
       
      Delete entity (recursive delete)

map_DispatchEntity

map_DispatchEntity applies the mapping enabled for the type of entity passed in. If more than one mapping is defined for a single DTF, they are invoked in order for each call to map_DispatchEntity.

   Get DTF of entity
   if (multiple mappings exist for this DTF)
      Invoke next mapping
   else
      Invoke appropriate mapping function based on DTF

map_CommitEntity

map_CommitEntity commits the results of a mapping. Entities that are not transient must be recursively copied before being flagged as committed. Transient entities, however, can simply be flagged as committed. Committed entities are added to the info->list if applicable. The following pseudocode demonstrates:

   if (entity is not transient)
      Recursively duplicate entity into appropriate model
      committed_entity = new duplicate entity
      
   else   /* entity is transient */
      committed_entity = entity
      
   Flag committed_entity as committed so
          map_ProcessEntity will not delete it
   if (info->list is defined)
      Add committed_entity to the list