All Frameworks  Class Hierarchy  This Framework  Indexes

AutomationInterfaces Class CATScriptUtilities

CATScriptUtilities
 

Usage: you must use this class as is. You should never derive it.


public class CATScriptUtilities

Class to provide utility functions which simplify the use of the scripting interfaces.


Method Index


o ExecuteScript(CATUnicodeString&,CatScriptLibraryType,CATUnicodeString&,CATVariant&,CATUnicodeString&,CATVariant*,unsigned int,CATBoolean)
A short-cut method which runs, from an interactive program or a macro, a function written in a scripting language synchronously.
o GetScriptErrorNotification()
Returns the name of the event event notification sent whenever a script raises an error.
o GetScriptInterruptNotification()
Returns the name of the event event notification sent whenever a script is interrupted.
o GetScriptStartNotification()
Returns the name of the event notification sent whenever a script begins its execution.
o GetScriptStopNotification()
Returns the name of the event event notification sent whenever a script stops its execution.
o IsMacroPlayerOn()
Returns true if a macro is currently being replayed.
o IsMacroRecorderOn()
Returns true if a macro is currently being recorded.
o SetAutomationErrorMessage(CATUnicodeString&)
Sets a custom error message which will be caught by the script engines and displayed in the UI as a replacement of the default error message ("The method XXX has failed").

Methods


o ExecuteScript
public static HRESULT __stdcall ExecuteScript( const CATUnicodeString& iLibraryName,
CatScriptLibraryType iType,
const CATUnicodeString& iProgramName,
CATVariant& oResult,
const CATUnicodeString& iFunctionName= "CATMain",
CATVariant* iParams= NULL,
unsigned int iParamCount= 0,
CATBoolean iAutomaticReplay= TRUE)
A short-cut method which runs, from an interactive program or a macro, a function written in a scripting language synchronously. ExecuteScript will return only once the scripted function has finished running. This method works only in a CATIA V5 interactive program or a macro.
CAUTION: This method must be called on time-out, using CATApplication.AddTimeOut . The sample below illustrates how to call it on time-out. If you would not call it on time-out, a script which calls one of the following method will not work: The method illustrated in the sample below is the only method to run any script.
Parameters:
iLibraryName
The library in which the script is contained
iLibraryType
The type of the library
iProgramName
The name of the program in the library
oResult
The value returned by the function (if any)
iFunctionName
The name of the function to invoke
iParameters
An C++ array of parameters for the function
iParamCount
The size of the parameter array.
iAutomaticReplay
Specifies whether the replay is automatic or if it is explicitly done from a user interaction.
Example:
This example illustrates how to call this method on time-out. It describes how to migrate from a CATStateCommand, named CAAMyStateCommand, which would run ExecuteScript synchronously, to a CATStateCommand which would run ExecuteScript on time-out.
Instead of:
  • a transition, and its associated action, which:
    • run the script synchronously
    • do the actions which must be ran after the script execution
  • the transition triggering during execution making pass from a CATDialogState named SourceState to a CATDialogState named DestinationState
we will have:
  • a transition executing the first part of the preceeding solution: it adds a call-back on time out, the call-back running the script
  • this transition makes pass from a CATDialogState named SourceState to a CATDialogState named IntermediaryState
  • during execution, when the current state will be IntermediaryState, the preceeding call-back will be executed. This call-back runs the script, and triggers the other transition
  • another transition executing the second part of the preceeding solution: do the actions which must be ran after the script execution
  • this transition makes pass from IntermediaryState to a CATDialogState named DestinationState
Your code will be the following:
  • CAAMyStateCommandInteractionNotifier.h:
    #ifndef CAAMyStateCommandInteractionNotifier_H
    #define CAAMyStateCommandInteractionNotifier_H
    #include "CATCommand.h"
    class CATNotification;   
    class CAAMyStateCommandInteractionNotifier: public CATCommand
    { public:
      CAAMyStateCommandInteractionNotifier();
      virtual ~CAAMyStateCommandInteractionNotifier();
      void Advise(CATCommand* ToClient, CATNotification* Notif);
    };
    #endif
  • CAAMyStateCommandInteractionNotifier.cpp:
    #include "CAAMyStateCommandInteractionNotifier.h"
    #include "CATCommand.h"
    #include "CATNotification.h"
    CAAMyStateCommandInteractionNotifier::CAAMyStateCommandInteractionNotifier() 
    {}
    CAAMyStateCommandInteractionNotifier::~CAAMyStateCommandInteractionNotifier()
    {}
    void CAAMyStateCommandInteractionNotifier::Advise(CATCommand* ToClient, CATNotification* Notif)
    { SendNotification(ToClient,Notif); }
  • CAAMyStateCommandNotification.h:
    #ifndef CAAMyStateCommandNotification_H
    #define CAAMyStateCommandNotification_H
    #include "CATNotification.h"
    class CAASourceStateToIntermediaryStateNotif : public CATNotification
    { CATDeclareClass;
      public:
        CAASourceStateToIntermediaryStateNotif();
        virtual ~CAASourceStateToIntermediaryStateNotif();
    };
    class CAAIntermediaryStateToDestinationStateNotif : public CATNotification
    { CATDeclareClass;
      public:
        CAAIntermediaryStateToDestinationStateNotif();
        virtual ~CAAIntermediaryStateToDestinationStateNotif();
    };
    class CAADestinationStateToNULLStateNotif : public CATNotification
    { CATDeclareClass;
      public:
        CAADestinationStateToNULLStateNotif();
        virtual ~CAADestinationStateToNULLStateNotif();
    };
    #endif
  • CAAMyStateCommandNotification.cpp:
    #include "CAAMyStateCommandNotification.h"
    CATImplementClass(CAASourceStateToIntermediaryStateNotif,Implementation,CATNotification,CATNull);
    CAASourceStateToIntermediaryStateNotif::CAASourceStateToIntermediaryStateNotif() {}
    CAASourceStateToIntermediaryStateNotif::~CAASourceStateToIntermediaryStateNotif() {}
    CATImplementClass(CAAIntermediaryStateToDestinationStateNotif,Implementation,CATNotification,CATNull);
    CAAIntermediaryStateToDestinationStateNotif::CAAIntermediaryStateToDestinationStateNotif() {}
    CAAIntermediaryStateToDestinationStateNotif::~CAAIntermediaryStateToDestinationStateNotif() {}
    CATImplementClass(CAADestinationStateToNULLStateNotif,Implementation,CATNotification,CATNull);
    CAADestinationStateToNULLStateNotif::CAADestinationStateToNULLStateNotif() {}
    CAADestinationStateToNULLStateNotif::~CAADestinationStateToNULLStateNotif() {}
  • CAAMyStateCommand.h:
    #ifndef CAAMyStateCommand_h
    #define CAAMyStateCommand_h
    #include "CATStateCommand.h"
    #include "CATPanelAcquisition.h"
    #include "CAAMyStateCommandNotification.h"
    #include "CAAMyStateCommandInteractionNotifier.h"
    #include "CATPathElement.h"
    #include "CATNotifier.h"
    class CATDialogAgent;
    class CAAMyStateCommand: public CATStateCommand
    { CmdDeclareResource(CAAMyStateCommand,CATStateCommand);
      public:
      CAAMyStateCommand( );
      virtual ~CAAMyStateCommand();
      virtual CATStatusChangeRC Activate(CATCommand*	iFromClient,CATNotification*	iNotification);
      virtual CATStatusChangeRC Desactivate(CATCommand*	iCmd,CATNotification*	iNotification);
      virtual CATStatusChangeRC Cancel(CATCommand*	iCmd,CATNotification*	iNotification);
      virtual void BuildGraph();
      static void sRunScriptAndTriggerSecondPartTransition(CATCommand* iCAAMyStateCommand,int iSubscribedType,
                                                           CATString* iScriptName);
      static int sOccurenceCount; // The purpose of this variable is to avoid instances of the current
                                  // CATStateCommand which do not exist any more to be used.
                                  // In the following scenario:
                                  //  - the CAA developer uses a CATStateCommand
                                  //  - the CATStateCommand runs a script on time-out
                                  //  - the script calls the automation method Documents.Open, giving it a Part
                                  //    as parameter
                                  //  - during execution, only a Product is open, and CAAMyStateCommand is ran 
                                  // we have:
                                  //  - the CAAMyStateCommand::sRunScriptAndTriggerSecondPartTransition
                                  //    call-back is executed
                                  //  - Documents.Open is executed
                                  //  - we enter the "Part Design" workbench
                                  //  - The "Select" command ask to become active
                                  //  - we go through the CAAMyStateCommand destructor
                                  //  - we go out of the script
                                  //    - - -> From now, 
                                  //           CAAMyStateCommand::sRunScriptAndTriggerSecondPartTransition must
                                  //           not use anymore the CAAMyStateCommand instance
      CAASourceStateToIntermediaryStateNotif* _CAASourceStateToIntermediaryStateNotif;
      CAAIntermediaryStateToDestinationStateNotif* _CAAIntermediaryStateToDestinationStateNotif;
      CAADestinationStateToNULLStateNotif* _CAADestinationStateToNULLStateNotif;
      CATBoolean FirstPartTransitionAction(void *data);
      CATBoolean SecondPartTransitionAction(void *data);      
      CATBoolean EndCommandTransitionAction(void *data);
      static CAAMyStateCommandInteractionNotifier* sInteractionNotifier;        
      CATDialogAgent* _FirstPartDialogAgent;
      CATDialogAgent* _SecondPartDialogAgent;
      CATDialogAgent* _EndCommandDialogAgent;
      CATString _ScriptName;
    };
    #endif
  • CAAMyStateCommand.cpp:
    #include "CAAMyStateCommand.h"
    #include "CAAMyStateCommandNotification.h"
    #include "CATApplication.h"
    #include "CATScriptUtilities.h"
    #include "CATAutoConversions.h"
    #include "CATDialogAgent.h"
    #include "CATGetEnvValue.h"
    CAAMyStateCommandInteractionNotifier*  CAAMyStateCommand::sInteractionNotifier  = NULL;
    int CAAMyStateCommand::sOccurenceCount = 0;
    void CAAMyStateCommand::sRunScriptAndTriggerSecondPartTransition(
                            CATCommand* iCAAMyStateCommand,int iSubscribedType,
                            CATString* iScriptName)
    { CATLibStatus LibOK;
      CATUnicodeString FolderName;
      CAAIntermediaryStateToDestinationStateNotif* CAAIntermediaryStateToDestinationStateNotif = NULL;
      CAAMyStateCommand* MyStateCommand;
      CATDialogAgent* SecondPartDialogAgent = NULL;
      CATApplication* Application = NULL;
      char* CATTempValue = NULL;
      CATVariant VariantReturnValue;
      long ReturnValue;
      HRESULT hr;
     	Application = CATApplication::MainApplication();
      MyStateCommand = (CAAMyStateCommand*)iCAAMyStateCommand;
      CAAIntermediaryStateToDestinationStateNotif = 
        MyStateCommand->_CAAIntermediaryStateToDestinationStateNotif;
      SecondPartDialogAgent = MyStateCommand->_SecondPartDialogAgent;
     	// We run the "CATMain" sub of the "MyScript.catvbs" script located in the place specified by
      // the CATTemp environment variable 
      LibOK = CATGetEnvValue("CATTemp",&CATTempValue);
      if (LibOK == CATLibSuccess) 
        { FolderName = CATTempValue; ReturnValue = 0;
          hr = BuildVariant((const long)ReturnValue,VariantReturnValue);
         	hr = CATScriptUtilities::ExecuteScript(FolderName,catScriptLibraryTypeDirectory, 
    		                                           iScriptName->CastToCharPtr(),VariantReturnValue,
    		                                           "CATMain");
        }
      if (sOccurenceCount!=0)
        { // we trigger the second part transition
          sInteractionNotifier->Advise(SecondPartDialogAgent->GetFather(),
                                       MyStateCommand->_CAAIntermediaryStateToDestinationStateNotif);
        }
    }
    CAAMyStateCommand::CAAMyStateCommand():
      CATStateCommand ("CAAMyStateCommand",CATCommandModeExclusive) 
      ,_FirstPartDialogAgent(NULL),_SecondPartDialogAgent(NULL)
    { _CAASourceStateToIntermediaryStateNotif = new CAASourceStateToIntermediaryStateNotif();
      _CAAIntermediaryStateToDestinationStateNotif = new CAAIntermediaryStateToDestinationStateNotif();
      _CAADestinationStateToNULLStateNotif = new CAADestinationStateToNULLStateNotif();
      sInteractionNotifier = new CAAMyStateCommandInteractionNotifier();
      sOccurenceCount++;
    }
    CAAMyStateCommand::~CAAMyStateCommand()
    { if (_CAASourceStateToIntermediaryStateNotif!=NULL) 
        { _CAASourceStateToIntermediaryStateNotif->Release(); _CAASourceStateToIntermediaryStateNotif = NULL; }
      if (_CAAIntermediaryStateToDestinationStateNotif!=NULL) 
        { _CAAIntermediaryStateToDestinationStateNotif->Release(); _CAAIntermediaryStateToDestinationStateNotif = NULL; }
      if (_CAADestinationStateToNULLStateNotif!=NULL) 
        { _CAADestinationStateToNULLStateNotif->Release(); _CAADestinationStateToNULLStateNotif = NULL; }
      if (_FirstPartDialogAgent!=NULL)  
        { _FirstPartDialogAgent->RequestDelayedDestruction(); _FirstPartDialogAgent = NULL; }
      if (_SecondPartDialogAgent!=NULL)  
        { _SecondPartDialogAgent->RequestDelayedDestruction(); _SecondPartDialogAgent = NULL; }
      if (_EndCommandDialogAgent!=NULL)  
        { _EndCommandDialogAgent->RequestDelayedDestruction(); _EndCommandDialogAgent = NULL; }
      if (sInteractionNotifier!=NULL) 
        { sInteractionNotifier->RequestDelayedDestruction(); sInteractionNotifier = NULL; }
      sOccurenceCount--;
    }
    CATStatusChangeRC CAAMyStateCommand::Activate (CATCommand* FromClient,CATNotification* EvtDat )
    { return (CATStatusChangeRCCompleted); }
    CATStatusChangeRC CAAMyStateCommand::Desactivate (CATCommand* iCmd,CATNotification* iNotification)
    { return (CATStatusChangeRCCompleted); }
    CATStatusChangeRC CAAMyStateCommand::Cancel (CATCommand* iCmd,CATNotification* iNotification)
    { return (CATStatusChangeRCCompleted); }
    void CAAMyStateCommand::BuildGraph()
    { CATDialogState* SourceState = NULL;
      CATDialogState* IntermediaryState = NULL;
      CATDialogState* DestinationState = NULL;
      // we fill the dialog agents
      _FirstPartDialogAgent = new CATDialogAgent("CAASourceStateToIntermediaryStateNotif");
      _FirstPartDialogAgent->AcceptOnNotify(sInteractionNotifier,_CAASourceStateToIntermediaryStateNotif);
      _SecondPartDialogAgent = new CATDialogAgent("CAAIntermediaryStateToDestinationStateNotif");
      _SecondPartDialogAgent->AcceptOnNotify(sInteractionNotifier,_CAAIntermediaryStateToDestinationStateNotif);
      _EndCommandDialogAgent = new CATDialogAgent("CAADestinationStateToNULLStateNotif");
      _EndCommandDialogAgent->AcceptOnNotify(sInteractionNotifier,_CAADestinationStateToNULLStateNotif);
      // we fill the states
      SourceState = GetInitialState("CAAMyStateCommandSourceState");
      SourceState->AddDialogAgent(_FirstPartDialogAgent);
      IntermediaryState = AddDialogState("CAAMyStateCommandIntermediaryState");
      IntermediaryState->AddDialogAgent(_SecondPartDialogAgent);
      DestinationState = AddDialogState("CAAMyStateCommandDestinationState");
      DestinationState->AddDialogAgent(_EndCommandDialogAgent);
      // we fill the transitions
      AddTransition(SourceState,IntermediaryState,
                    IsOutputSetCondition(_FirstPartDialogAgent),
        			         Action((ActionMethod) &CAAMyStateCommand::FirstPartTransitionAction));
      AddTransition(IntermediaryState,DestinationState,
                    IsOutputSetCondition(_SecondPartDialogAgent),
        			         Action((ActionMethod) &CAAMyStateCommand::SecondPartTransitionAction));
      AddTransition(DestinationState,NULL,
                    IsOutputSetCondition(_EndCommandDialogAgent),
        			         Action((ActionMethod) &CAAMyStateCommand::EndCommandTransitionAction));
      // we trigger the first part transition
      sInteractionNotifier->Advise((CATDialogAgent*)_FirstPartDialogAgent->GetFather(),
                                   _CAASourceStateToIntermediaryStateNotif);
    }
    CATBoolean CAAMyStateCommand::FirstPartTransitionAction(void *data)
    { CATApplication* Application = NULL;
      // insert here the actions which must be ran before the script execution
    
      // we set the sRunScriptAndTriggerSecondPartTransition call-back on time-out
     	Application = CATApplication::MainApplication();
      _ScriptName = "MyScript.catvbs";
      Application->AddTimeOut(1,this,&_ScriptName,
                              (void(*)())sRunScriptAndTriggerSecondPartTransition);	
      // we prevent _FirstPartDialogAgent to be valued any more through the notification
      _FirstPartDialogAgent->IgnoreOnNotify(sInteractionNotifier,_CAASourceStateToIntermediaryStateNotif);
    
      return TRUE;
    }
    
    CATBoolean CAAMyStateCommand::SecondPartTransitionAction(void *data)
    { // insert here the actions which must be ran after the script execution
    
      // we prevent _SecondPartDialogAgent to be valued any more through the notification
      _SecondPartDialogAgent->IgnoreOnNotify(sInteractionNotifier,_CAAIntermediaryStateToDestinationStateNotif);
      // we trigger the end command transition
      sInteractionNotifier->Advise(_EndCommandDialogAgent->GetFather(),_CAADestinationStateToNULLStateNotif);
    
      return TRUE;
    }
    CATBoolean CAAMyStateCommand::EndCommandTransitionAction(void *data)
    { // we prevent _EndCommandDialogAgent to be valued any more through the notification
      _EndCommandDialogAgent->IgnoreOnNotify(sInteractionNotifier,_CAADestinationStateToNULLStateNotif);
      return TRUE; 
    }
o GetScriptErrorNotification
public static char* __stdcall GetScriptErrorNotification()
Returns the name of the event event notification sent whenever a script raises an error.
o GetScriptInterruptNotification
public static char* __stdcall GetScriptInterruptNotification()
Returns the name of the event event notification sent whenever a script is interrupted.
o GetScriptStartNotification
public static char* __stdcall GetScriptStartNotification()
Returns the name of the event notification sent whenever a script begins its execution.
o GetScriptStopNotification
public static char* __stdcall GetScriptStopNotification()
Returns the name of the event event notification sent whenever a script stops its execution.
o IsMacroPlayerOn
public static CATBoolean __stdcall IsMacroPlayerOn()
Returns true if a macro is currently being replayed.
o IsMacroRecorderOn
public static CATBoolean __stdcall IsMacroRecorderOn()
Returns true if a macro is currently being recorded.
o SetAutomationErrorMessage
public static HRESULT SetAutomationErrorMessage( const CATUnicodeString& iMessage)
Sets a custom error message which will be caught by the script engines and displayed in the UI as a replacement of the default error message ("The method XXX has failed").
Parameters:
iMessage
The error message to display

This object is included in the file: CATScriptUtilities.h
If needed, your Imakefile.mk should include the module: CATAutoItf

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