RADE

Principles

When SCM commands are executed, some controls are performed to check the validity of command's arguments.
These controls are realized by some checkers, especially:

• one checker for verifying the architecture of components
  • imbrication of directories (framework, module or simple directory)
  • directory and file naming
  • unicity of some components or files
• one checker to determine whether a Unix path is a network path or a local path
• one checker for verifying customer rules when a software object (framework, module, data, directory or element) is created, modified, deleted or imported.
• one checker for verifying customer rules at each promotion request
• one checker for verifying customer rules when importing software object changes by adl_force_so_chg command

	Those checkers are located outside the configuration management kernel and gathered in a shared library that we will call the default library in the rest of this paper.
	For a given installation of the SCM product, it is possible to create a new library which will define some checkers for verifying specific rules. We will call this library the custom library.
	We will see that it is also possible to call the default checkers from the custom library.

[Top]

Interactions Between the Kernel and The Checker Libraries

Each time a command is executed, the arguments to be checked are passed to the corresponding checkers if exist. Some checkers can be found either in the default library or in the custom library:

• if the Custom library exists and contains the wanted checker, this checker is called instead of the default one
• if the Custom library does not exist or exist but does not export the wanted checker, the default checker is chosen

We will see afterwards that it is also possible to call the default checkers from the custom checkers. So, depending on what has been written in the body of a custom checker, it is possible

• to change the rules that are verified by the kernel (by writing new code)
• to inhibit some of them (just returning "S_OK")
• to add new rules in addition to the default ones (by wrting new code and calling the corresponding default checker)

[Top]

Implementing Custom Checkers

Prerequisites

It is possible to build a custom library without having a full CAA V5 development environment installed. Only a C++ compiler is needed. The compilation and the creation of the library are performed by a specific tool.

[Top]

The External Checker Interface

The custom library must export two functions that are recognized by the SCM kernel and that are called when loading the custom library.
Here are their definitions:

const char *ADLCMGetAPIVersion();

This function must not be modified and is used by the kernel to avoid any inconsistency between the kernel and the custom library (especially when further versions of SCM will be installed upon an existing installation)

HRESULT ADLCMInitAPI(ADLCMAPIInterface &APIInterface)

This function is always called by the kernel and it allows

• the custom library to know the default checkers (located in the default library).
  Then it will be able to call them from the custom checkers
• the custom library to provide its own checkers in place of the default ones

The custom library sample that is provided with SCM performs the two operations: it registers the references to the default checkers and provides its own checkers

The other functions that are defined in the custom library are those corresponding to the custom checkers. To know the list of default checkers that can be redefined, consult the ADLCMAPIInterface class definition which propose a SetXXX() method for each XXX default checker.

Actually there are five checkers that can be defined in the custom library:

HRESULT ADLCMCheckArchiRules(ADLCMCheckArchiRulesArgs)

HRESULT ADLCMCheckIfUnixPathIsShared(ADLCMCheckIfUnixPathIsSharedArgs)

HRESULT ADLCMCheckSoftObj(ADLCMCheckSoftObjArgs)

HRESULT ADLCMCheckPromotionRequest(ADLCMCheckPromotionRequestArgs)

HRESULT ADLCMCheckFlow(ADLCMCheckFlowArgs)

In further SCM versions, it will be possible that other functions can be defined in the custom library. It is the reason why the ADLCMGetAPIVersion function must be implemented by the custom library.

[Top]

Calling Kernel Utilities

The custom library is initialized using the ADLCMInitAPI function. This function receives in input an instance of the class ADLCMAPIInterface which provides some methods for managing errors and messages in a format that can be handled by the kernel.

ADLCMAPIMsgBldrCtlg * MakeMsgBldrCtlg(const char *Catalog, const char *Code) 

This method is used for creating a NLS message builder from a usual CAA message catalog file. See the section "Installing the Custom Checker Library" to know where such a message file can be delivered

HRESULT SetLastError(const char *SourcePath, 
                            int SourceLine,
                            ADLCMAPIMsgBldr *pRequestBldr,
                            ADLCMAPIMsgBldr *pDiagnosticBldr,
                            ADLCMAPIMsgBldr *pAdviceBldr,
                            ADLCMAPIErrorType ErrorType = ADLCMAPIErrorTypeCritical,
                            HRESULT hr = E_FAIL) 

This method is used for raising an error and defining the associated messages (which have been defined using the method MakeMsgBldrCtlg).

The following sample shows how to return to the SCM kernel an error with a relevant message:

• the error code is initialized with S_OK
• an error is set using the SetLastError method
• the error messages are found in the ADLCMD NLS message file with indexes "0525", "0526" and "0527"

HRESULT hr = S_OK;
...
if (! UnixSharedPathFound)
   {
      ADLCMAPIMsgBldrCtlg *pRequestBldr = GetAPIInterface().MakeMsgBldrCtlg("ADLCMD", "0525"); // "Check the Unix network path \"/p1\""
      pRequestBldr->AddNewParameter(Path);

      ADLCMAPIMsgBldrCtlg *pDiagnosticBldr = GetAPIInterface().MakeMsgBldrCtlg("ADLCMD", "0526"); // "The Unix network path \"/p1\" is invalid."
      pDiagnosticBldr->AddNewParameter(Path);

      ADLCMAPIMsgBldrCtlg *pAdviceBldr = GetAPIInterface().MakeMsgBldrCtlg("ADLCMD", "0527"); // "Use /p1 option or choose between the following path: /p2"
      pAdviceBldr->AddNewParameter(LocalPathOptionName);
      pAdviceBldr->AddNewParameter("/u/lego/, /u/users/");

      hr = GetAPIInterface().SetLastError(__FILE__, __LINE__, pRequestBldr, pDiagnosticBldr, pAdviceBldr);

      delete pRequestBldr;
      delete pDiagnosticBldr;
      delete pAdviceBldr;
   }
return hr;
}

[Top]

Calling Default Checkers

It is interesting to call a default checker when specific tests must be performed in addition to the default ones.

Considering a default checker whose name is XXX and which can be redefined, the ADLCMAPIInterface class provides two methods either

• for getting the reference to this default checker: it is the method ADLCMAPIInterface::DfltXXX()
• for replacing the default checker by a custom checker: it is the method ADLCMAPIInterface::SetXXX()

Then if you want to call a default checker from your own function, you have just to call the appropriate DlftXXX() method and to set its arguments with the values you want. This method will return a HRESULT value that will be tested to know whether the call was successful or not.

The following example shows the default checker called from the custom checker in the case where the object to be checked is a framework:

HRESULT ADLCMCheckArchiRules(
        const ADLCMAPIParsedProjPath &APIParsedProjPath,
        int ProjElemIdx,
        const char *User,
        Boolean &UnicityWithExtension,
        Boolean &UnicityInFolder)
{
   HRESULT hr = S_OK;

   if (APIParsedProjPath.GetProjElem(ProjElemIdx).GetProjElemType() == ADLCMAPIProjElem::ArchiFramework)
      // Framework -> default check
      hr = GetAPIInterface().DfltCheckArchiRules(
                                        APIParsedProjPath,
                                        ProjElemIdx,
                                        User,
                                        UnicityWithExtension,
                                        UnicityInFolder);
      else if (Type == ADLCMAPIProjElem::ArchiModule)
      ...

[Top]

The ADLCMCheckArchiRules Checker

This checker is called for every file or directory path given as argument to a SCM command (once per argument).

HRESULT ADLCMCheckArchiRules(
	const ADLCMAPIParsedProjPath &APIParsedProjPath,
	int ProjElemIdx,
	const char *User,
	Boolean &UnicityWithExtension,
	Boolean &UnicityInFolder)
{
...
}

Parameters

• const ADLCMAPIParsedProjPath &APIParsedProjPath: the element (file or directory) to be checked under a specific format allowing the checker to access each part of the path
  • the path is split into pieces corresponding to the directories between the workspace root directory and the element to be checked
  • the ADLCMAPIParsedProjPath class provides methods for accessing each piece
  • the first piece correspond to a framework, the second one to module or directory, etc
• int ProjElemIdx: the piece of path of the element for which the checker is called by the SCM kernel (0 for the first part, 1 for the second part, etc)
• const char *User: it is the name of the current user
• Boolean &UnicityWithExtension: if the element must be checked by the SCM kernel as unique, this boolean must be set to "TRUE" if this control must be performed considering the extension.
  Note that there is no default value for this boolean and it's up to the custom checker to set it explicitly.
• Boolean &UnicityInFolder: must be set to "TRUE" if the kernel must verify that the given element is unique only in the embedding folder and must be to "FALSE" if the element must be unique in the whole workspace tree.
  Note that there is no default value for this boolean and it's up to the custom checker to set it explicitly.

For instance, when the user runs the command adl_mk_elem Fw/module.m/src/foo.cpp, the ADLCMCheckArchiRules checker is called with the following arguments:

• APIParsedProjPath
  • APIParsedProjPath.GetLastProjElem().GetProjName() returns foo.cpp
  • APIParsedProjPath.GeNbProjElem() returns 3
  • APIParsedProjPath.GetLastProjElem().GetProjElemType() returns ArchiFileElement
  • APIParsedProjPath.GetLastProjElem().SoftObjIsComponent() returns false
  • APIParsedProjPath.GetProjElem(1).GetProjElemType() returns ArchiModule
  • APIParsedProjPath.GetProjElem(1).SoftObjIsComponent() returns true
• ProjElemIdx = 3
• User = current user

Default checker

The rules enforced by the default checker are described in a dedicated paper [1]. Please consult it for learning more about the rules.

[Top]

The ADLCMCheckIfUnixPathIsShared Checker

This checker is called to check if a given UNIX path should be considered like a network path or not; that is to say that it will be considered by SCM command as referencing the same file system from any UNIX host of the current SCM installation. See the sample's sources for a full implementation of this checker.

HRESULT ADLCMCheckIfUnixPathIsShared(const char *Path, const char *LocalPathOptionName)
{
...
}

Parameters

• const char *Path: It is the full Unix path to be checked.
• const char *LocalPathOptionName: it is the name of the SCM option that is used for specifying a local path (see adl_mk_ws or adl_mk_image commands). This string can be used if the path is not correct and if you want to display a message in which you remind the option to be used for a local path.

Default checker

The Unix paths that are considered as shared paths must begin either by /u/users or by /u/lego [2].

[Top]

The ADLCMCheckSoftObj Checker

This checker is called to check customer rules when a software object (framework, module, data, directory or element) is created, modified, deleted or imported. In the adl_mk_fw, adl_mk_mod, adl_mk_data, adl_mk_dir, adl_mk_elem, adl_co, adl_mv, adl_rm, adl_unrm, adl_import commands, for each software object treated this checker is called just before the validation of the action. See the sample's sources for a full implementation of this checker.

HRESULT ADLCMCheckSoftObj(
	const ADLCMAPIParsedProjPath &APIParsedProjPath,
	const ADLCMAPIParsedProjPath *pTargetAPIParsedProjPath,
	const char *CommandName,
	const char *User,
	const char *CurrentWsTree,
	const char *CurrentWs,
	const char *CurrentImage)
{
...
}

Parameters

• const ADLCMAPIParsedProjPath &APIParsedProjPath: Path of the software object to be checked under a specific format allowing the checker to access each part of the path
  • the path is split into pieces corresponding to the directories between the workspace root directory and the object to be checked
  • the ADLCMAPIParsedProjPath class provides methods for accessing each piece
  • the first piece correspond to a framework, the second one to module or directory, etc
• const ADLCMAPIParsedProjPath *pTargetAPIParsedProjPath: Target path under a specific format allowing the checker to access each part of the path. If the software object is moved, pTargetAPIParsedProjPath is valued.
• const char *CommandName: Name of the running command
• const char *User: Name of the current user
• const char *CurrentWsTree: Current workspace tree. See Structure of workspace tree parameter.
• const char *CurrentWs: Current workspace. See Structure of workspace parameter.
• const char *CurrentImage: Current image in the workspace tree. See Structure of image in a workspace tree parameter.

No Default checker

[Top]

The ADLCMCheckPromotionRequest Checker

This checker is called for every promotion request in adl_promote command just before the validation of the transaction. See the sample's sources for a full implementation of this checker.

HRESULT ADLCMCheckPromotionRequest(
	const char *SoftObjChangesFilePath,
	const char *User,
	const char *CurrentWsTree,
	const char *CurrentWs,
	const char *PromotedWsRev,
	const char *TargetWs,
	const char *CurrentImage,
	Boolean Simulation)
{
...
}

Parameters

• const char *SoftObjChangesFilePath: File path containing software object changes to promote. See Structure software object changes file.
• const char *User: Name of the current user
• const char *CurrentWsTree: Current workspace tree. See Structure of workspace tree parameter.
• const char *CurrentWs: Current workspace. See Structure of workspace parameter.
• const char *PromotedWsRev: Promoted workspace revision. See Structure of workspace revision parameter.
• const char *TargetWs: Target workspace (workspace collector) of the promotion request. See Structure of workspace parameter.
• const char *CurrentImage: Current image in the workspace tree. See Structure of image in a workspace tree parameter.
• Boolean Simulation: TRUE if the command is executed in simulation mode (-simul option).

No Default checker

[Top]

The ADLCMCheckFlow Checker

This checker is called for every import with the adl_force_so_chg command just before the validation of the transaction. 

HRESULT ADLCMCheckFlow(
	const char *FlowDataFilePath,
	const char *CommandName,
	const char *User,
	const char *CurrentWsTree,
	const char *CurrentWs,
	int NbOriginWsRev,
	const char *OriginWsRev[],
	const char *CurrentImage,
	Boolean Simulation)
{
...
}

Parameters

• const char *FlowDataFilePath: File path containing flow data : the software object changes imported, the attached components, the merges to solve, .... See Structure flow data file.
• const char *CommandName: Name of the running command
• const char *User: Name of the current user
• const char *CurrentWsTree: Current workspace tree. See Structure of workspace tree parameter.
• const char *CurrentWs: Current workspace. See Structure of workspace parameter.
• int NbOriginWsRev: Number of origin workspace revisions. Now, it is always 1.
• const char *OriginWsRev: Array of origin workspace revisions from which the software object modifications come. See Structure of workspace revision parameter.
• const char *CurrentImage: Current image in the workspace tree or "<NULL>" if no current image. See Structure of image in a workspace tree parameter.
• Boolean Simulation: TRUE if the command is executed in simulation mode (-simul option).

No Default checker

[Top]

Structure of Checkers Parameters

Some parameters are complex objects with some attributes. They are described in one string with fields.

• the first field is a keyword
• the fields are separated by a pipe character "|"
• for one field, if several values are accepted, they are listed separated by a pipe character "|"
• the <...> notation indicates a string. See dealing with strings.

Structure of Workspace Tree Parameter

• WS_TREE : keyword 
• <WsTreeCaseName> : case name of the workspace tree
• <WsTreeId> : unique database identifier of  the workspace tree (computed by SCM)
• <ContentsServerHostName> : contents server hostname associated to the workspace tree
• <ContentsServerPort> : contents server port number associated to the workspace tree
• <DatabaseUpperName> : database upper name where the workspace tree is created
• CHECK_CAA_RULES | NO_CHECK_CAA_RULES : indicates wether CAA rules are checked or not for all workspaces of the workspace tree
• NONE | OPTIONAL | MANDATORY : change request management mode (Internal Dassault-Systèmes)
• <SoftwareLevel> : software level value

Structure of Workspace Parameter

• WORKSPACE: keyword 
• <WsCaseName> : case name of the workspace
• <WsId> : unique database identifier of  the workspace (computed by SCM)
• <WsTreeCaseName> : case name of the workspace tree
• <WsTreeId> : unique database identifier of  the workspace tree (computed by SCM)
• AUTOMATIC_MERGE | NOT_AUTOMATIC_MERGE : indicates whether merges can be solved automatically or by user help
• PROMO_REQ_LOCKED | PROMO_REQ_NOT_LOCKED : indicates whether promotion requests are allowed or not
• PROMO_FROM_ANY_WS | PROMO_FROM_CHILD_WS : indicates whether promotion requests can come only from child workspaces or also from the parent workspace
• SYNC_CMD_ALLOWED | SYNC_CMD_FORBIDDEN : indicates whether an adl_sync command can be run in this workspace
• PROMOTE_CMD_ALLOWED | PROMOTE_CMD_FORBIDDEN : indicates whether an adl_promote command can be run in this workspace
• MERGE_AT_COLLECT_ALLOWED | MERGE_AT_COLLECT_FORBIDDEN : indicates whether merges are allowed when running the adl_collect command
• SYNC_FOR_PROMO | NOT_SYNC_FOR_PROMO : indicates whether child workspaces must synchronize themselves before being allowed to promote
• FLOW_TRACES_STORED | FLOW_TRACES_NOT_STORED : indicates whether the traces produced by flow commands (adl_collect, etc) are stored
• DEVELOPMNT | MULTILEVEL | CERTIF : kind of workspace for the change request management tool (Internal Dassault-Systèmes)
• DEFAULT | AUTOMATIC | MANUAL : publication type (see adl_set_ws -publication_type)
• CHECK_CAA_RULES|NO_CHECK_CAA_RULES|<NULL> : indicates whether CAA rules are checked or not. <NULL> if it is not defined
• NONE|OPTIONAL|MANDATORY|<NULL> : Change request management mode (Internal Dassault-Systèmes). <NULL> if it is not defined
• <SoftwareLevel> : The software level value

Structure of Image in a Workspace Tree Parameter

• IMAGE_IN_TREE: keyword 
• <ImageCaseName> : case name of the image
• <ImageId> : unique database identifier of  the image (computed by SCM)
• WINDOWS | UNIX : indicates the platform the image has been created on
• <ImageCaseProjectionPath> : absolute path to the projection directory
• <LocalHostName> | <NETWORK> : the "<NETWORK>" string indicates that the image's path is a network path, otherwise the hostname where the image has been created
• REFRESHED | NOT_REFRESHED : indicates whether the image is refreshed in this workspace tree

Structure of Workspace Revision Parameter

• WS_REV: keyword 
• <WsRevRank> : revision number (rank) of the workspace <WsCaseName> in the tree <WsTreeCaseName>
• <WsRevHistoryRank> : history rank of the workspace <WsCaseName> in the tree <WsTreeCaseName> (internal version number computed by SCM)
• <WsRevId> : unique database identifier of  the workspace revision (computed by SCM)
• <ConfigRevId> : unique database identifier of the configuration revision (computed by SCM)
• <WsCaseName> : case name of the workspace
• <WsId> : unique database identifier of  the workspace (computed by SCM)
• <WsTreeCaseName> : case name of the workspace tree
• <WsTreeId> : unique database identifier of  the workspace tree (computed by SCM)

Structure of Software Object Changes File

The file contains software object changes grouped by software object. For each modified software object, we found the _SOFT_OBJ line and for each change type the _SO_CHG_GRP_CR, __SO_CHG and ___CREATED lines.

Structure of Flow Data File

The flow data file contains:

• The software object changes grouped by software object. For each modified software object, we found the _SOFT_OBJ line and for each change type the _SO_CHG_GRP_CR, __SO_CHG and ___CREATED lines.
• Software objects moved out _SOFT_OBJ_MOVED_OUT_FROM
• Attached components _ATTACHED_COMPONENT 
• Software objects which create projection conflicts _PROJECTION_CONFLICT
• Deleted merges. One line per deleted merge (couple of software object and change type) with information
  • _DELETED_MERGE
  • <SoftObjPath> : relative path to the software object
  • DEL | NOT_DEL : state of the software object, seen as deleted or not
  • <SoftObjId> : unique database identifier of the software object (computed by SCM)
  • FRAMEWORK | MODULE | DATA | DIR_ELEM | FILE_ELEM : software object type
  • FOLDER | FILE : the software object is a directory or a file
  • COMPONENT | ELEMENT : the software object is a component or an element. A component is either a framework, a module or a data. An element is a directory or a file and belongs to a component. 
  • CH_DELETED | MOVE | CH_DESCR | CH_CONTENT | CH_EXEC: SCM modification type
• Merge to solve _MERGE_TO_SOLVE

[Top]

Sample

A sample of the custom library is provided in the SCM installation: considering the directory specified when downloading the CAA RADE V5 CD-ROM, you should find the sample in XXX/resources/Adele/CustRulesLib directory (XXX can be intel_a, solaris_a, aix_a, etc).

As an example, here is a view on a Windows installation: The MakeInstall.bat file is used to generate the library. The ADLCMCustRules.h and ADLCMCustRules.cpp files contain examples of what can be found in a custom library. The other .h files contain the definitions of the different classes needed for compiling: ADLCMAPIInterface.h ADLCMAPIMsgBldr.h and ADLCMAPIMsgBldrCtlg.h (error and NLS message utilities) ADLCMAPIParsedProjPath.h etc The msgcatalog directory contains an example of a english NLS message file and this directory can contain sub-directories depending the language supported by the custom library (French, German, Japanese, etc)

[Top]

Building the Custom Checker Library

If you want to use your own tools to generate the custom library, just copy the source files under your environment, generate the library and install it with the NLS message files (if any) by following what is explained in the installation section. Otherwise you can use the MakeInstall program located in the directory where the sample source files are stored and execute it.

The purpose of the MakeInstall program is

1. to compile all the source files
2. to link the derived objects to produce the custom library
3. create a runtime view gathering the library and the message files

Before using the tool, check the following prerequisites:

• create a temporary directory which will be used as a target directory for producing the library
• the C++ compiler and linker are found in PATH
• change the current working directory to the one containing the source files (.cpp and .h) and the "msgcatalog" directory.

Here is an example where the library is produced under the temporary directory E:\MyLib:

MakeInstall E:\MyLib
##############################################
                Initialization
##############################################
msgcatalog\ADLCMCUSTRULES.CATNls
msgcatalog\French\ADLCMCUSTRULES.CATNls
2 File(s) copied
##############################################
                Compilation
##############################################
ADLCMCustRules.cpp
ADLCMCustStringUtilities.cpp
##############################################
                 Link-edit
##############################################
   Creating library e:\MyLib\ADLCMCustRules\code\bin\ADLCMCustRules.lib and object e:\MyLib\ADLCMCustRules\code\bin\ADLCMCustRules.exp
##############################################
                   End
##############################################
Directory PATH listing
Volume serial number is 0012FC94 8C79:E0CF
E:\MYLIB\ADLCMCUSTRULES
+---code
¦   +---bin
¦           ADLCMCustRules.dll
¦           ADLCMCustRules.exp
¦           ADLCMCustRules.lib
¦           ADLCMCustRules.pdb
¦
+---resources
    +---msgcatalog
        ¦   ADLCMCUSTRULES.CATNls
        ¦
        +---French
                ADLCMCUSTRULES.CATNls

The directory e:\MyLib\ADLCMCustRules has been successfully created.

[Top]

Installing the Custom Checker Library

Once the custom library generated, it must become visible by SCM commands. This is done using the ADL_CUST_RULES_LIB environment variable.

There are two cases:

• If the library and the message files are copied into the standard CAA RADE runtime view,
  set the ADL_CUST_RULES_LIB variable with just the library identifier, for instance ADLCMCustRules in our example
• If the library and the message files are stored somewhere outside the standard CAA RADE runtime view.
  set the ADL_CUST_RULES_LIB variable with the full path name of the library, for instance E:\mylib\ADLCMCustRules\code\bin\ADLCMCustRules.dll in our example.

Where to set this variable?

The best way should be to edit the SCM initialization profile [3] and to add the setting of this variable.

[Top]

In Short

The controls performed by SCM commands on their arguments can be changed by building a custom library and referencing it from the SCM initialization profile.

[Top]

References

History

Copyright © 2000, Dassault Systèmes. All rights reserved.