13.5 - Examining and Changing Plans

Table of Contents

• 13.5.1 Iterating Through the Statements in a Plan
• 13.5.2 Modifying a Plan Programmatically
  • 13.5.2.1 Adding Statements to a Plan
  • 13.5.2.2 Finding a Statement
  • 13.5.2.3 Removing Statements from a Plan

Plans are a list of ordered statements that are issued to an entity for execution.

If you want to extend or modify plans programmatically, it is helpful to understand how the DtPlan class and related classes are structured.

Note

If you are just adding a new kind of task or set data request statement, you do not have to make any plan-specific changes. The DtTaskStmt and DtSetDataRequestStmt plan statement classes accommodate new types automatically. Please see 12.3 - Adding a New Task for an Entity and 12.7 - Creating a New DtSetDataRequest.

13.5.1 Iterating Through the Statements in a Plan

A plan contains a top-level "Main" block of DtSimStatements. A block is a DtSimBlock (simBlock.h) object that contains a list of DtSimStatements, in the order they are to be executed. (The DtPlan’s main block is actually a derived type of DtSimBlock, a DtPlanBlock (planBlock.h).) The following is an example of a plan.

(Plan 
   (plan-name "15 Plt, 1 Force")
   (Block 
      (Set 
         (set-data-request-type "set-heading")
         (heading  1.570796)
      )
      (Task 
         (task-type "move-to")
         (control-point  "white")
      )
   )
)

The DtSimBlock provides accessors for looking up DtSimStatements by an integer statement ID, as well as iterating through the statements in the block. For example, to iterate through the main block of statements and display information about each one:

DtPlan* aPlan;

DtSimStatement* aStmt;

. . .

for (aStmt = aPlan->mainBlock()->firstStmt(); aStmt; aStmt = aStmt->nextStmt())
{

   // stringRep() returns a string representation of the statement
   // (as seen in the view and edit plan windows)
   DtInfo("String representation for statement %d: %s\n", aStmt->id(),
      aStmt->stringRep().string());
}

This example iterates through just the top-level statements in a plan, that is, the list of DtSimStatements contained in its main block of statements. Statements may contain subblocks of statements, such as the set of statements that gets conditionally executed inside If and When statements. To access the statement block in a DtIfStmt (ifStmt.h), call the thenBlock() and elseBlock() member functions. To access the block of statement block in a DtWhenStmt (whenStmt.h), call the whenBlock() member function. All of the subblock accessors return pointers to derived types of DtSimBlocks. You can treat these blocks in the same way as you would the DtPlanBlock, that is, you can get the count of statements contained in the block, look up a statement by its integer ID, and iterate through the statements in the block.

13.5.2 Modifying a Plan Programmatically

You can create and edit plans through code. You might want to do this if, for example, you want to create or modify a plan in the back-end (instead of reading it in from a file).

13.5.2.1 Adding Statements to a Plan

To add a statement to a plan, you add a statement to the appropriate block of statements in the plan. The block may be the main block of statements owned by the DtPlan (a DtPlanBlock, returned by the mainBlock() accessor()), or it may be the subblock of an If (DtIfStmt) or When (DtWhenStmt) statement. DtIfStmts contain thenBlock() and elseBlock() member functions, which return pointers to its subblocks. When statements contain a whenBlock() member function pointing to its single subblock. Using these accessors, you can add a statement to the appropriate place in a plan.

For example, to create a When statement that contains a single task statement, and then add the When statement (containing the task statement in its subblock) to the plan:

DtPlan* aPlan;
DtWhenStmt *whenStmt;
DtTaskStmt *taskStmt;

// Add the task statement to the When statement's subblock
whenStmt->whenBlock()->add(taskStmt);

// Add the When statement (containing the task statement) to the main plan
// block (making it a top-level statement)
aPlan->add(whenStmt);

The add() call adds the statement to the end of the list of statements in the block. To add a statement at the beginning of the list call addToStart(). To insert a statement after a statement already in the list, call addAfter().

Note

When you add a statement to a block, the block assumes responsibility for deleting the memory associated with the statement, so you may want to clone the statement being passed in (if you expect to continue to need the statement outside the block).

13.5.2.2 Finding a Statement

When you create a new statement, its constructor automatically generates a statement ID (a unique integer identifier). The DtSimStatement class has a statementId() accessor that returns this ID. You can use the statement ID to look up a particular statement in the main block of a plan, or in a statement with subblocks. To look up a statement with a specific ID in a plan’s main block of statements, do the following:

int stmtId;

DtSimStatement* stmt = aPlan->mainBlock()->lookupStatement(stmtId);

if(stmt)
{
   DtInfo("Found statement %d\n", stmt->statementId());
}

Note

When you call lookupStatement() in a block (a plan block, or a subblock in a statement), it only searches for the statement in that block. It does not search recursively through the statements’ subblocks.

13.5.2.3 Removing Statements from a Plan

To delete a statement from a plan, call the removeAndDelete() member function in the DtSimBlock that owns the statement. The removeAndDelete() function removes the statement from the block, and deletes the memory associated with the statement.

To delete a top-level statement in a plan, delete the statement from the plan’s main block of statements, for example:

DtPlan* aPlan;
DtSimStatement* aStmt;

aPlan->mainBlock()->removeAndDelete(aStmt);

To delete a statement in a subblock of an If or When statement, call removeAndDelete() in that subblock.

To remove and delete all of the statements in a plan, call removeAllAndDelete() in the plan’s main block, for example:

DtPlan* aPlan;

aPlan->mainBlock()->removeAllAndDelete();

[<< The Plan Administrator] [Home] [Top of Page] [Executing a Plan >>]