Building Components

3D PLM PPR Hub Open Gateway	PDM Object Hub	Building Components How to build an Express schema, user functions for Express-X mapping, and an Express-X mapping schema
Use Case

This task will introduce the various building components and you will learn how to build:

an express schema
user functions for Express-X mapping
an Express-X mapping schema

First of all, you have to create your file tree. A file Tree has several fixed levels of directories.

At the first level of your workspace (MyWorkspace in our example) we find directories corresponding to components. These components are called frameworks. The example below shows a framework (MyFramework) containing the basic V5 architecture, i.e. the IdentityCard and ProtectedInterfaces directories.

Even if the file tree shows a flat view of the frameworks, there are relationships between them. Different relationships exist but they have quite the same meaning, that is to say that a given framework uses the resources exported by one or more other frameworks. Those frameworks are called prerequisites.

Such relationships are expressed in a special file called the IdentityCard.h file. Any framework - whatever its type is (code, education, test) - must provide an IdentityCard file in which it defines its prerequisite frameworks. The IdentityCard file is the privileged (and unique) place where the relationships between a framework and its prerequisites are expressed: this is a convenient way for users and tools to have a knowledge of an application architecture.

A framework being a component, it is not supposed to expose all of its resources to its clients, but only the minimum. This contributes to maintain the system modular and understandable.

By the way, the file tree defines several directories whose purpose is to gather the public part of any component, resources are made public through an "interface". Several interfaces can be exposed by one framework.

The different directories we can found under a framework correspond to different scopes of resources:

PublicInterfaces: contains the interfaces that are available for frameworks of other modelers
ProtectedInterfaces: contains the interfaces that are available for the frameworks of the modeler to which this framework belongs
PrivateInterfaces: contains interfaces that the framework wants to provide but for its own needs. These interfaces are not visible outside the framework scope (see also next section)

Framework interfaces can be implemented in several types of files/languages:

C++: the file suffix is .h
IDL: the file suffix is .idl

[Top]

Building an Express Schema

In our example, this schema will be called MySchema.

Enter the following prerequisites in the IdentityCard.h file:

AddPrereqComponent("SDMRuntime",  Protected);
AddPrereqComponent("VPMServices", Protected);

Initialize the build environment by launching the command:
```
mkInit
```
Launch the following command to call the prerequisites:
```
mkGetPreq
```

Under your framework, create a module named MySchema.m. In this module, create a Imakefile.mk file as follows:

BUILT_OBJECT_TYPE=SHARED LIBRARY
###############
OS = COMMON
###############
PROGRAM_NAME =
LOCAL_CKMFLAGS= -gLate

In this module, create a src directory containing:
1. a MySchema.cpp file to launch dynamically the schema library in Runtime defined as follows:
```
#include "CATSchemaMacro.h"
LoadSchemaDico (MySchema);
```
2. a MySchema.exsrc file, where the .cpp file will be generated, containing:
```
Private
```
In the ProtectedInterfaces directory, insert the MySchema.express schema to be built. The file tree now looks like this:
At the framework level, launch the build command:
```
mkmk -au
```

[Top]

Building a User Function for Express-X Mapping

Mapping may use user functions. These functions must be defined as follows:

Create a module called My_UserFcts.m in the framework where the user functions will be defined.

In this module, create a Imakefile.mk file containing at least:

BUILT_OBJECT_TYPE = SHARED LIBRARY
#############
OS = COMMON
#############
LINK_WITH= KS0LATE KS0SMPL
LOCAL_CKMFLAGS= -gLate

In this module, create then a directory containing the .cpp files (i.e. user functions): Fct_1.cpp, Fct_2.cpp, etc.

In the ProtectedInterfaces directory, create a header called My_UserFcts.h where the user functions will be declared:

#ifndef My_UserFcts_H
#define My_UserFcts_H

#ifdef _WINDOWS_SOURCE
#ifdef __My_UserFcts
#define ExportedByMy_UserFcts __declspec(dllexport)
#else
#define ExportedByMy_UserFcts __declspec(dllimport)
#endif
#else
#define ExportedByMy_UserFcts
#endif

ExportedByMy_UserFcts SdaiPrimitiveH Fct_1.cpp(const SdaiPrimitiveH& Param1,
                                               const SdaiPrimitiveH& Param2);

ExportedByMy_UserFcts SdaiPrimitiveH Fct_2.cpp(const SdaiPrimitiveH& Param1);
#endif

At the framework level, launch the following build command:
```
mkmk -au
```
The file tree now looks like this:

[Top]

Building an Express-X Mapping Schema

In our example, this schema will be called My_MAPPING.

Initialize the build environment.
Add the prerequisites in the IdentityCard.h file as follows:
```
AddPrereqComponent("SDMExpressX", Protected);
```

Launch the following command to call the prerequisites:

mkGetPreq -p path_directory where frameworks are stored

Build the schemas to be mapped by using the command:
```
mkmk -au
```
The Express schemas that will be mapped using Express-X mapping must have been previously built (see above paragraph).

If you want to build a mapping schema called My_MAPPING that maps the My_SCHEMA_1 and My_SCHEMA_2 schemas, the architecture will be the following one:
Create a module with the same name as the mapping schema in the framework.

In this module, create a Imakefile.mk file as follows:

BUILT_OBJECT_TYPE = SHARED LIBRARY
#############
OS = COMMON
LINK_WITH = KS0LATE KS0SIMPL KS0EXXMAP My_UserFcts
LOCAL_CKMFLAGS= -gLate

In this module, create a directory called src containing the mapping file called My_MAPPING.exx.
At the framework level, launch the build command:
```
mkmk -au
```
At this step, the mapping can be compiled but it will not be usable with the Import / Export / Migration platform. Because the tool calls the mapping dynamically, this mapping has to be seen as a Mapper. In other terms, it must adhere to the “VPMIExMapper” interface. Therefore an implementation of the interface has to be written to be able to use the mapping.

In MyMapping.m, create a new directory called LocalInterfaces.

In this directory create a new file called ds_MyMapping.h and write the following lines inside (do not forget to change MyMapping with your real name):

#ifndef ds_MyMapping_H
#define ds_MyMapping_H
#include "CATBaseUnknown.h"
#include "CATIContainer.h"
#include "StdMapper.h"

class ds_MyMapping : public StdMapper
{
  CATDeclareClass;

  public:

   ds_MyMapping();
   ~ds_MyMapping();
        
        //--------------------------------
        // Implementation for VPMIExMapper
        //--------------------------------
  HRESULT Convert(const CATIContainer_var& fromContner,
                  const CATIContainer_var& toContner);
};
#endif

In MyMapping.m/src, create a new file ds_MyMapping.cpp and write the following lines inside:

#include <iostream.h>
#include "ds_MyMapping.h"
CATImplementClass(ds_MyMapping, DataExtension, StdMapper, MyMapping);
ds_MyMapping::ds_MyMapping()
{
}
ds_MyMapping::ds_MyMapping()
{
}
#include "TIE_VPMIExMapper.h"
TIE_VPMIExMapper(ds_MyMapping);
//==============================================================
//
        Data Mapping
//==============================================================
HRESULT ds_MyMapping::Convert(const CATIContainer_var& fromContner, const
                              CATIContainer_var& toContner)
{
  HRESULT Stone = S_OK;
  CATUnicodeString TheMappingName((this->GetImpl())->IsA());
  //-------------
  // Data mapping
  //-------------
  Stone = ((StdMapper*)this)->Convert(fromContner, toContner, TheMappingName);
  return Stone;
}

To build this code, you need to add the following prerequisites:

In the Imakefile.mk

LINK_WITH = GUIDVPMSTEPExchanges \
            JS0GROUP \
            ENOVSTEPTools

In the IdentityCard.h of MyFramework
```
AddPrereqComponent("VPMDataMigration",  Protected);
AddPrereqComponent("VPMSTEPExchanges", Protected);
```
Now the module MyMapping.m can be built: mkmk –u under the module.

MyMapping is the late type given for this implementation. It will enable a dynamic loading of the mapping for the run-time.

Launch the command under the workspace:
```
MkGetPreq –p /thePath_where_the_frame_wokrs_are_stored
```
It has to be previously declared in the Dictionary:
- If the “CNext” directory does not exist, create the directory CNext in the Frame Work MyFramework.
- In CNext, create the directory code. In this code, create a directory called dictionary and edit MyFramework.dico.
- Add the following line:
```
MyMapping  VPMIExMapper  libMyMapping
```
In order to take MyFramework.dico into account, do not forget to export the variable in the runtime environment:
```
Export CATDictionaryPath=/…/MyWorkspace/MyFramework/CNext/code/dictionary:$CATDictionaryPath
```
These ds_MyMapping files can be stored in a new module.
A Unix shell is provided to generate the ds_MyMapping files: EV5_EXGener.sh (–h to display the parameters).

3D PLM PPR Hub Open Gateway

PDM Object Hub