Edit the campaign's recipe object

In order to set up a campaign or batch recipe edit object, the user must be presented with recipe information so that selections can be made. For example, if a recipe has multiple steps that require unit binding selections, the user needs to make those selections. All of the recipe information to be presented to the user can be accessed from the DeltaV software using the DVBCMExecRecipeInfo object. This object exposes many properties and methods that return various pieces of information consistent with how the recipe has been configured in Recipe Studio.

To retrieve the DVBCMExecRecipeInfo object, first get the list of recipes available. The DVBCMExecInfo object keeps this list. The following code shows an example.

Private Sub GetBaseRecipe()
    Dim objExecOnfo As DVBCMExecInfo
    Dim objExecRecipeInfo As DVBCMExecRecipeInfo
    Dim strExecNode As String
    ' Get the executive node name
    strExecNode = DVBCMClient.ExecutiveNode
    'Set the Executive info object
    Set objExecInfo = DVBCMClient.ExecutiveInfo(strExecNode)
    Call UseExecInfo(objExecInfo)
End Sub

Once an executive recipe object is retrieved, a list of all recipes on the executive can be retrieved for the user to select the new campaign's base recipe and to obtain an executive recipe information object.

Private Sub UseExecInfo(objExecInfo)
    Dim vRecipes() As String
    Dim strRecipeName As String
    Dim objExecRecipeInfo As DVBCMExecRecipeInfo
    ' Get list of recipes
    vRecipe = objExecInfo.ExecutiveRecipeList
    ' User Selects base recipe from list of recipes
    Call UserSelectsRecipe(vRecipes, strRecipeName)
    ' Retrieve executive recipe object
    objExecRecipeInfo = objExecInfo.ExecutiveRecipeInfo(strRecipeName)
    Call UseExecRecipeInfo(objExecRecipeInfo, objExecInfo)
End Sub

As the recipe is selected, specific information about that recipe such as formulas and bound units, can be retrieved from the DVBCMExecRecipeInfo and DVBCMExecParamInfo objects. As the formula and bound unit information is retrieved from the executive, it can be presented to the user for selection.

Private Sub UseExecRecipeInfo(objExecRecipeInfo, objExecInfo)
    Dim vFormulas() As String
    Dim vStepNames() As String
    Dim vUnitClasses() As String
    Dim vUnitNames() As String
    Dim vIsClassBased() As Boolean
    Dim lUnitIDs() As Long
    Dim vAreaNames() As String
    Dim lAreaIDs() As Long
    ' Get a list of each recipe step along with its associated unit class
    Call objExecRecipeInfo.GetStepsAndBoundUnits(vStepNames, _
        vUnitClasses, vIsClassBased)
    ' Get the bound units for each step
    Call SetBoundUnits(vStepNAmes, vUnitClasses, vIsClassBased, _
        vUnitNames, lUnitIDs, vAreaNames, lAreaIDs, objExecInfo)
    'Get a list of formulas for this recipe
    vFormulas = objExecRecipeInfo.FormulaList
    Call SetFormulaAndParameters(vFormulas)
End Sub

A bound unit must be selected for each step of the recipe. A list of units for each unit class can be retrieved from a DVBCMExecInfo object using the GetExecutiveUnitInfo method. The user must be presented with a list of possible units for each step. As the list of unit names is being presented, a list of unit IDs, area names and area IDs is also retrieved and presented for selection. If the recipe is not unit class based and the GetExecutiveUnitInfo method is passed a unit name instead of a unit class name, the method will just return the unit passed in. To determine if a step is associated with an individual unit or a unit class, check the vIsClassBased parameter passed to GetStepsAndBoundUnits above. Each entry in this array will be true if the corresponding step is based off a unit class.

Private SetBoundUnits(vStepNames, vUnitClasses, vIsClassBased,
    vUnitNames, lUnitIDs, vAreaNames, lAreaIDs, objExecInfo)
    Dim strBoundUnit As String
    Dim iSteps As Long
    Dim iCount As Long
    iSteps = Ubound(vStepNames)
    for iCount = 1 to iSteps
        if vIsClassBased(iCount) then
            Call ObjExecInfo.GetExecutiveUnitInfo(strBoundUnit, _
                vUnitNames, 1UnitIDs, vAreaNames, 1AreaIDs)
            Call PromptUserForBoundUnit(strBoundUnit, vUnitNames)
        Else
            strBoundUnit = vUnitClasses(iCount)
        End if
    next iCount
End Sub

Once a list of formulas is retrieved the user can be prompted for a formula name. With the formula name the GetFormulaInfo method can be called from DVBCMExecRecipeInfo object to retrieve the description, version, parameter names and parameter values of the formula. These can all be used to display information to the user about the formula or to allow the user to enter a custom formula with custom parameter values. With a specific parameter name, a DVBCMExecParamInfo object can be retrieved to display information about a parameter such as default value, high scale and low scale, as well as to tell if it can be edited or scaled. If custom parameter values are entered, the user must provide a unique formula name to be added to the server. If no formula is selected for the new campaign, the default values of all the parameters will be used.

Private Sub SetFormulaAndParameters(vFormulas)
    Dim strFormulaName As String
    Call PromptUserForFormula(vFormulas, strFormulaName)
End Sub

Once all the recipe information has been selected and maintained in variables, a recipe edit object can be retrieved to set all the properties of the campaign's recipe edit object. The only other property the user needs to enter is the recipe's scale.

Private Sub SetCampaignRecipeObject(ByRef objCampaignEdit As _
    IDVBCMCampaignEdit4, vStepNames As Variant, vUnitNames As Variant, _
    lUnitIDs As Variant, vParameterNames As Variant, vParameterValues As _
    Variant, strFormula As String, strExecNode As String)
    Dim fScale As float
    Dim objRecipeEdit As DVBCMRecipeEdit
    ' Prompt user for recipe's scale
    Call GetScaleFromUSer(fScale)
    ' Get the campaign's recipe edit object
    objRecipeEdit = objCampaignEdit.RecipeEdit
    Call objRecipeEdit.SetScale(fScale)
    objRecipeEdit.Formula = strFormula
    Call objRecipeEdit.SetUnitBindings(vStepNames, vUnitNames, _
        lUnitIDs)
    Call objRecipeEdit.SetParameters(vParameterNames, _
        vParameterValues)
End Sub

SetUnitBindings must be sent a valid list of step names along with a list of valid bound units for each step. If either list is incorrect, then when DVBCMCampaignEdit.SetupComplete is called for the campaign, the call will fail due to invalid unit selections for the base recipe of the campaign. The function SetUnitBinding can be used in instead to set one unit at a time but this is mainly used to change bound units after the campaign has been created. For the initial setup of a campaign all unit bindings are usually set.

SetParameters must be sent a valid list of parameter names and valid parameter types or, as with the unit bindings, the DVBCMCampaignEdit.SetupComplete call will fail. The function SetParameter can be used to set one parameter at a time but SetParameters is used at the initial setup of the campaign to set all parameters at once.