Setting a Name to an Action at Creation Time

Lifecycle Applications	Action Editor	Setting a Name to an Action at Creation Time Implementing CATIVpmUEActionFlow
Use Case

Abstract

The document is related to the use case CAAVpiAFLUserExit. It describes how to implement a user-exit for constructing and setting names to Actions when they are being created.

What You Will Learn With This Use Case
The CAAVpiAFLUserExit Use Case

What Does CAAVpiAFLUserExit Do
How to Launch CAAVpiAFLUserExit
Where to Find the CAAVpiAFLUserExit Code

Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to help you make your first steps in programming user-exits. More particularly, it shows how to implement a user-exit that is called by the ActionFlow (AFL) modeler.

[Top]

The CAAVpiAFLUserExit Use Case

CAAVpiAFLUserExit is a use case of the CAAVpiInterfaces.edu framework that illustrates VPMInterfaces framework functionalities.

[Top]

What Does CAAVpiAFLUserExit Do

The goal of CAAVpiAFLUserExit use case is to show how to implement a particular user-exit that is called by the ActionFlow modeler whenever an Action is created. This user-exit gives an application designer to set customized names for the Action being created.

To do so, the use case goes through the following steps:

Create an Action of type "Action_Design". This step is implemented in the file CAAVpiAFLUserExit.cpp which also includes the main program. Remember that it is the function which creates the Action which will trigger the user-exit.
Implement the user-exit called "GetActionName" by performing the following steps:

get the action which being created
construct a name by concatenating the Action type "Action_Design" and the current date.
Assign the constructed name to the new Action.

The actual implementation of the user-exit is contained in the file CAAVpiAFLUserExit_GetActionName.cpp.

[Top]

How to Launch CAAVpiAFLUserExit

To launch CAAVpiAFLUserExit, you will need to set up the build-time environment, next compile CAAVpiAFLUserExit along with its prerequisites, then set up the run-time environment, and finally execute the use case [1].

Launch the use case as follows:

With Windows

e:>CAAVpiAFLUserExit

With UNIX

$ CAAVpiAFLUserExit

[Top]

Where to Find the CAAVpiAFLUserExit Code

The CAAVpiAFLUserExit use case is made of two source files named CAAVpiAFLUserExit.cpp and CAAVpiAFLUserExit_GetActionName.cpp, both located in the module CAACAAVpiAFLUserExit.m of the framework CAAVPMInterfaces.edu.

Windows	`InstallRootDirectory\CAAVPMInterfaces.edu\CAAVpiAFLUserExit.m\`
Unix	`InstallRootDirectory/CAAVPMInterfaces.edu/CAAVpiAFLUserExit.m/`

Where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

[Top]

Step-by-Step

There are six main steps in CAAVpiConfigurateStructure Code:

Prolog
Getting a ActionFlow Manager
Creating an Action
Implementing the User Exit
Getting the Current Action from the AFL Pool
Constructing a Name and Passing it Back to the Modeler

We will now comment each of these sections in detail.

[Top]

Prolog

CAAVpiAFLUserExit.cpp creates first an Action of type "Action_Design". CAAVpiAFLUserExit_GetActionName implements the user-exit by constructing a name under the form <ActionType>_<CurrentDate>.

[Top]

Getting a Configuration Manager

...
  // Get a session
  VPMSession* session = VPMSession::OpenSession();
...
  // Get a factory manager from the session
  CATIVpmFactoryManager_var factoryMgr = NULL_var;
  session->GetVPMObjectFactory(factoryMgr);
...
  // Query an interface on CATIVpmAFLManager
  CATIVpmAFLManager_var aflMgr(factoryMgr);
...

The ActionFlow Manger manages some object creations as well as their lifecycles. Examples are Actions and AffecetedObjects. It also provides usefull functions to query various types of objects.

A session is needed to retrieve a smart pointer to the standard FactoryManager. An interface query on CATIVpmAFLManager is then performed to retrieve the specific ActionFlow manager.

CATIVpmAFLManager The ActionFlow Manager interface

[Top]

Creating an Action

...
  // Create an action of type Action_Design
  CATIVpmAFLAction_var action;
  CATUnicodeString actionType("Action_Design");
  rc = aflMgr->CreateAction(actionType, action);
...

An Action of type Action_Design is created with no name specified. It is the function CreateAction() which will attempt to create a user-exit object with late-type "VPMUEAFL_GetActionName". This means for a user-exit named XXX, the corresponding late-type must be called "VPMUEAFL_XXX". Furthermore, this latetype must adhere to interface CATIVpmUEActionFlow. An implementation of the user-exit for this late-type must then implement the method Run(CATListOfCATUnicodeString).

[Top]

Implementing the User Exit

As hinted above, to implement the user-exit, an implementation class must be defined for the latetype VPMUEAFL_GetActionName.
This class must then adhere to the interface CATIVpmUEActionFlow to implement the method Run().

...
//-----------------------------------------------------------------------------
// Implementation of CAAVpiAFLUserExit_GetActionName
//-----------------------------------------------------------------------------
CATImplementClass (CAAVpiAFLUserExit_GetActionName, DataExtension, CATBaseUnknown, VPMUEAFL_GetActionName);
...
#include "TIE_CATIVpmUEActionFlow.h"
TIEchain_CATIVpmUEActionFlow (CAAVpiAFLUserExit_GetActionName);
// Implementation of method CATIVpmUEActionFlow::Runt()
HRESULT  CAAVpiAFLUserExit_GetActionName::Run(CATListOfCATUnicodeString& ioList)
{ ...
  if (ioList[1]=="CREATION")
  {
    ...

The method Run() takes one in-out parameter of a list of String. At the method call, the first element of the list indicates the type of the user-exit. In our case case, it must be "CREATION" to make sure the user-exit code will be executed upon an Action creation.

...
  if (ioList[1]=="CREATION")
  {
    // Get a session
    VPMSession* session = VPMSession::OpenSession();
    ...
    // Get a factory manager from the session
    CATIVpmFactoryManager_var factoryMgr = NULL_var;
    session->GetVPMObjectFactory(factoryMgr);

    // Query an interface on CATIVpmAFLManager
    CATIVpmAFLManager_var aflMgr(factoryMgr);
    ...
    // Get the action from AFL pool
    CATIVpmAFLAction_var currentAction;
    aflMgr->GetActionFromAFLSimplePool(currentAction);
...

[Top]

Getting the Current Action from the AFL Pool

Before calling the user-exit for naming Action, the ActionFlow modeler pushes the current Action being created in to a pool. This way, when the user-exit is triggered, the Action just created and to be named can be extracted from that pool. The following shows how to get an Action from the ActionFlow pool.

...
    // Get a session
    VPMSession* session = VPMSession::OpenSession();
    ...
    // Get a factory manager from the session
    CATIVpmFactoryManager_var factoryMgr = NULL_var;
    session->GetVPMObjectFactory(factoryMgr);

    // Query an interface on CATIVpmAFLManager
    CATIVpmAFLManager_var aflMgr(factoryMgr);
    ...
    // Get the action from AFL pool 
    CATIVpmAFLAction_var currentAction;
    aflMgr->^...
  if (ioList[1]=="CREATION")
  {
    // Get a session
    VPMSession* session = VPMSession::OpenSession();
    ...
    // Get a factory manager from the session
    CATIVpmFactoryManager_var factoryMgr = NULL_var;
    session->GetVPMObjectFactory(factoryMgr);

    // Query an interface on CATIVpmAFLManager
    CATIVpmAFLManager_var aflMgr(factoryMgr);
    ...
    // Get the action from AFL pool 
    CATIVpmAFLAction_var currentAction;
    aflMgr->GetActionFromAFLSimplePool(currentAction);
...

After getting a session and the AFL factory manager, the function GetActionFromAFLSimplePool() is called.

[Top]

Constructing a Name and Passing it Back to the Modeler

Since the naming convention is the concatenation of the Action type and the current date, the type of the Action being created is first retrieved using method GetType() defined in interface CATIVpmAFLAction. A date is then computed and appended to the Action type. Once the Action name is constructed, it must be pushed in to the in-out list parameter as first element. It is the CreateAction() method which after the user-exit returns will set the returned name to the Action being created.

...
    // Declare the string to hold the final action name
    CATUnicodeString actionName;

    // First, get the action type and put it in the action name
    currentAction->GetType(actionName);

    // Get the current date and time and make it "readable"
    CATTime date = CATTime::GetCurrentLocalTime();
    CATUnicodeString strDate = date.ConvertToString("%c");
    CATUnicodeString strDay = strDate.SubString(8,2);
    if (strDay.SubString(0,1)==" ") strDay = "0"+strDay.SubString(1,1);

    // Concatenate the stringefied date to the action type
    actionName = actionName + "_" + strDate.SubString(4,3)+ strDay+ "-" +strDate.SubString(11,8)+ "-"+strDate.SubString(20,4);

    // Reset the ioList. The returned list will contain the constructed name that 
    // the AFL modeler will assign to the action being created
    ioList.RemoveAll();

    // Push the name into the list to be returned
    ioList.Append(actionName);

[Top]

In Short

This use case demonstrates how the user-exit technique can be used in the ActionFlow modeler to implement customized behavior.
As an example, a user-exit for naming Action at their creation is described.

[Top]

References

[1]	Building and Launching a CAA V5 Use Case
[Top]

History

Version: 1 [Nov 2001]	Document created
[Top]

Lifecycle Applications

Action Editor