Event Handlers (Profile)

CanCreate

[all objects] Used to implement a creation validation rule to prevent objects from being created in an invalid context. For example, in a BPM for ebXML, a process with a Business Transactions stereotype can only be created under a process with a Binary Collaboration stereotype. The script of the CanCreate event handler associated with the Business Transaction process stereotype is the following:

Function %CanCreate%(parent)
  if parent is Nothing or 
  parent.IsKindOf(PdBpm.Cls_Process) then
  %CanCreate% = False
  else
  %CanCreate% = True
  end if
End Function

If this event handler is set on a stereotype and returns True, then you can use the custom tool to create the stereotyped object. Otherwise the tool is not available, and the stereotype list excludes corresponding stereotype. If it is set on a metaclass and returns True, then you can create the object from the Toolbox, from the Browser or in a list.

Note that, when you import or reverse engineer a model, the CanCreate functions are ignored since they could modify the model and make it diverge from the source.

Initialize

[all objects] Used to instantiate objects with predefined templates. For example, in a BPM, a Business Transaction must be a composite process with a predefined sub-graph. The script of the Initialize event handler associated with the Business Transaction process stereotype contains all the functions needed to create the sub-graph. The following piece of script is a subset of the Initialize event handler for a Business Transaction.

...
' Search for an existing requesting activity 
     symbol
 Dim ReqSym  
 Set ReqSym = Nothing  
 If Not ReqBizAct is Nothing Then
  If ReqBizAct.Symbols.Count > 0 Then
   Set ReqSym = ReqBizAct.Symbols.Item(0)
  End If
 End If
 
 ' Create a requesting activity if not found
 If ReqBizAct is Nothing Then
   Set ReqBizAct =
      BizTrans.Processes.CreateNew 
   ReqBizAct.Stereotype =
     "RequestingBusinessActivity"
   ReqBizAct.Name = "Request"
 End If
...

If the Initialize event handler is set on a stereotype and returns True, the initialization script will be launched whenever the stereotype is assigned, either with a custom tool in the Toolbox, or from the object property sheet. If it is set on a metaclass and returns True, the initialization script will be launched when you create a new object from the Toolbox, from the Browser, in a list or in a property sheet.

If it is set on the model metaclass and returns True, the initialization script is launched when you assign a target (DBMS or object, process, or schema language) to the model at creation time, when you change the target of the model or when you attach an extension to the model.

Validate

[all objects] Runs when you change tabs or click OK or Apply in an object property sheet. Used to validate changes to object properties and to implement cascade updates.

You can define an error message that will appear when the condition is not satisfied. To do so, fill the message variable and set the %Validate% variable to False.

In the following example, the validate event handler verifies that a comment is added to the definition of an object when the user validates the property sheet. A message is displayed to explain the problem.

Function %Validate%(obj, ByRef message)
 if obj.comment = "" then 
  %Validate% = False
  message = "Comment cannot be empty"
 else
  %Validate% = True
 end if
End Function

CanLinkKind

[link objects only] Runs when you create a link with a Toolbox tool or modify link ends in a property sheet. Used to restrict the kind and stereotype of the objects that can be linked together.

This event handler has two input parameters: its source and destination extremities. You can also use the sourceStereotype and destinationStereotype parameters. These are optional and used to perform additional checks on stereotypes.

In the following example, the source of the extended link must be a start object:

Function %CanLinkKind%(sourceKind, 
  sourceStereotype, destinationKind,
  destinationStereotype)
 if sourceKind = cls_Start Then
 %CanLinkKind% = True
 end if
End Function

OnModelOpen

[models only] Runs immediately after a model is opened.

OnModelSave

[models only] Runs immediately before a model is saved.

OnModelClose

[models only] Runs immediately before a model is closed.

OnLanguageChangeRequest

[models only] Runs immediately before the model's DBMS or language definition file is changed. If the event handler returns false, then the language change is canceled.

OnLanguageChanging

[models only] Runs immediately after the model's DBMS or language definition file is changed, but before any transformations are applied to objects to make them conform with the new language definition.

OnLanguageChanged

[models only] Runs immediately after the model's DBMS or language definition file is changed and the object transformations are applied.

OnNewFromTemplate

[models only] Runs immediately after a model or a project is created from a model or project template.

BeforeDatabaseGenerate

[PDM models only] Runs immediately before generating a database.

AfterDatabaseGenerate

[PDM models only] Runs immediately after generating a database.

BeforeDatabaseReverseEngineer

[PDM models only] Runs immediately before reverse-engineering a database.

AfterDatabaseReverseEngineer

[PDM models only] Runs immediately after reverse-engineering a database.

GetEstimatedSize

[PDM only] Runs when the Estimate Database Size mechanic is called. For detailed information, see Modifying the Estimate Database Size Mechanism.