Desktop User Guides > Professional > Data management scripting > Data Management reference > Data Management functions
 
Data Management functions
Function
Description
Combines the response value for nested grid questions iterations
Transfers data from SourceGrid to DestinationGrid
Creates a summary result for a grid
Converts grid sub-questions into flattened questions
Retrieves flipped data from SourceGrid
Removes the deprecated OldCategory from MDMObject
Replaces oldCategory with newCategory for a loop/categorical questions
Subtracts the values for one or more questions
Sums the value for more than one categorical question
See also
Data Management reference
CombineIterations
Combines the response value for nested grid question iterations (used for OnNextCase events).
Syntax
CombineIterations(CombineQuestion, CombineIterationName, CombineList)
Parameters
CombineQuestion
Type: object
Grid question
CombineIterationName
Type: string
The iteration category that stores the combination results.
CombineList
Type: Categorical
The iteration category items that determine the result.
Return value
Type: Boolean
True if the function is successful.
Notes
Used to combine the value of sub-question(s) related to two iterations (by union operation). The results are saved in the sub-question related to another iteration named CombineIterationName.
There are restrictions when using this function:
▪CombineQuestion is categorical loop.
▪The loop can contain more than one type of sub-question. This function only process categorical questions.
▪Iteration CombineIterationName should exist in question CombineQuestion before the OnNextCase event. The iteration can be added via the .dms script metadata.
Example
CombineIterations(MyLoopCatQuestion, "NetAorB", {A,B})
NetAorB is one iteration category for MyLoopCatQuestion, and can be added as follows:
MetaData (ENU, Analysis, Label, myInputDataSource)

MyLoopCatQuestion - loop
{
NetAorB "Respondent chose either A or B"
} fields -
(
rating categorical [1..1]
{
LikeABit "LikeABit" Factor(3),
Like "Like" Factor(2),
Dislike "Dislike" Factor(1)
};
) expand grid;

End MetaData
After running the function, the results are as follows:
Iteration Name
Case 1
Case 2
A
{ ABitLike }
{ Dislike }
B
{ Like }
{ Dislike }
NetAorB
{ ABitLike , Like }
{ Dislike }
See also
Data Management functions
CopyGrid
Transfers data from SourceGrid to DestinationGrid (used for OnNextCase events). SourceGrid contains the originally collected data, while DestinationGrid stores the copied data. IterationFilter restricts iterations copied for DestinationGrid.
Syntax
CopyGrid(SourceGrid, DestinationGrid, IterationFilter)
Parameters
SourceGrid
Type: Object
Grid question
DestinationGrid
Type: Object
Grid question
IterationFilter
Type: Categorical
Categorical for iteration filter
(return)
Type: Boolean
True if copy is successful
Notes
If IterationFilter is null, data transfer from SourceGrid to DestinationGrid will be processed according to the iterations for DestinationGrid, otherwise according to the iterations in IterationFilter.
There might be some iterations or sub-questions in DestinationGrid that do not exist in SourceGrid. This function only copies the common iterations and sub-questions in DestinationGrid and SourceGrid.
Example
CopyGrid(Loop1, LoopForCopy, Null)
The definitions for Loop1 and LoopForCopy are as follows:
Loop1 - loop
{
A -,
B -,
C -,
D -
} fields -
(

Q1 "LikeOrNot" categorical [1..1]
{
Like -,
Dislike -
};
Q2 Text[20];
Q3 Long[1..5];

) expand grid;

LoopForCopy - loop
{
B -,
A -,
D -
} fields -
(
Q2 Text[20];
Q1 "LikeOrNot" categorical [1..1]
{
Like -,
Dislike -
};

) expand grid;
For the current record, the value for Loop1 is as follows:
LevelID
Q1
Q2
Q3
{A}
{ Dislike }
I am testing
2
{B}
{Like}
I am
2
{C}
{Dislike}
I
3
{D}
{Like}
I am t
4
The value for LoopForCopy is as follows:
LevelID
Q2
Q1
{A}
I am testing
{ Dislike }
{B}
I am
{Like}
{D}
I am t
{Like}
CopyGrid(Loop1, LoopForCopy, {A,B})
Based on this value for Loop1, the value for LoopForCopy will be as follows:
LevelID
Q2
Q1
{A}
I am testing
{ Dislike }
{B}
I am
{Like}
Performance note
CopyGrid can transfer data between grids for many scenarios. The grid might contain any type of question (single response, compound, block, nested grid, and so on). Use the following script example for better performance when the grid being copied has only one nested question:
For Each Iteration In Grid1
   Grid1_Copy[Iteration.QuestionName].Item[0].Response =
      Iteration.Item[0]
Next
See also
Data Management functions
CreateGridSummary
Creates a summary result for a grid (used for OnNextCase events).
Syntax
CreateGridSummary (Grid, SummaryVarible, SummaryCategories, QuestionNameForSummary)
Parameters
Grid
Type: None
The summarized grid question.
SummaryVariable
Type: None
The categorical question for saving summary results.
SummaryCategories
Type: None
The category list for calculating summary results.
QuestionNameForSummary
Type: Text
The name of sub-question in the summarized grid.
Notes
The function creates the summarized results for grid sub-questions and saves the results to the categorical question SummaryVariable. There can be more than one sub-question; QuestionNameForSummary is the only sub-question that is summarized.
There are restrictions when using this function:
▪The grid iteration categories are the same as defined categories for the categorical question SummaryVariable.
Example
CreateGridSummary (BrandsGrid, TopBrand2, {A,B}, "Rating")
BrandsGrid "BrandsGrid" loop
{
BrandA "BrandA",
BrandB "BrandB",
BrandC "BrandC",
BrandD "BrandD"
} fields -
(
Rating "Rating" categorical [1..]
{
A "_1",
B "_2",
C "_3",
D "_4",
E "_5"
};

LongRating "Rating" long [0 .. 10];

TextRating "Rating" text [10..10];

) expand grid;

BrandTop "Top 2 summary Brand" categorical[1..]
{
BrandA "BrandA",
BrandB "BrandB",
BrandC "BrandC",
BrandD "BrandD"
}
The value for BrandsGrid is as follows:
A
B
C
D
E
BrandA
√
 
√
 
 
BrandB
 
√
 
√
 
BrandC
 
 
√
√
√
BrandD
√
 
 
 
 
The value for the question TopBrand2 is:
{BrandA, BrandB, BrandD}
See also
Data Management functions
FlattenGrid
Converts categorical loop sub-questions (both grid and non-grid) into flattened questions that can be used in the DMOM event OnBeforeJobStart/OnAfterMetaDataTransformation.
Syntax
FlattenGrid(FlattenQuestionFullName, FilterIteration, MDMObject)
Parameters
FlattenQuestionFullName
Type: string
FullName for the question being flattened
FilterIteration
Type: string
String for the iteration filter
MDMObject
Type: object
MDM object related to the .mdd file that contains GridObjectName
(return)
Type: string
True if the function is successful.
Notes
The generated questions are saved on the top level in the .mdd file related to MDMObject. The policy for avoiding duplicate question names is to append _1, _2, _n to the default question name.
Examples
FlattenGrid("MyLoopCatQuestion.rating", Null, MDMObject)
The definition for MyLoopCatQuestion is as follows:
MyLoopCatQuestion - loop
{
A "A",
B "B",
C "C",
D "D"
} fields -
(
rating categorical [1..1]
{
LikeABit "LikeABit",
Like "Like",
Dislike "Dislike"
};

) expand grid;
The generated, flattened questions are as follows:
A_rating categorical
expression("MyLoopCatQuestion[{A}].rating");

B_rating categorical
expression("MyLoopCatQuestion[{B}].rating");

C_rating categorical
expression("MyLoopCatQuestion[{C}].rating");

D_rating categorical
expression("MyLoopCatQuestion[{D}].rating");
FlattenGrid ("MyLoopCatQuestion.rating", "a,b", MDMObject)
Then newly created variables are as follows:
A_rating categorical
expression("MyLoopCatQuestion[{A}].rating");

B_rating categorical
expression("MyLoopCatQuestion[{B}].rating");
FlattenGrid ("ComplexLoop.Grid1", "a,b", MDMObject)
The definition for ComplexLoop is as follows:
ComplexLoop - loop
{
A "A",
B "B",
C "C",
D "D"
} fields -
(
Grid1 - loop
{
1 "1",
2 "2",
3 "3"
} fields -
(
rating categorical [1..1]
{
ABitLike "ABitLike",
Like "Like",
Dislike "Dislike"
};

) expand grid;

) expand grid;
The generated, flattened questions are as follows:
ComplexLoop_A_1_rating categorical
expression("ComplexLoop[{A}].Grid1[{1}].rating");

ComplexLoop_A_2_rating categorical
expression("ComplexLoop[{A}].Grid1[{_2}].rating");

ComplexLoop_A_3_rating categorical
expression("ComplexLoop[{A}].Grid1[{_3}].rating");

ComplexLoop_B_1_rating categorical
expression("ComplexLoop[{B}].Grid1[{_1}].rating");

ComplexLoop_B_2_rating categorical
expression("ComplexLoop[{B}].Grid1[{_2}].rating");

ComplexLoop_B_3_rating categorical
expression("ComplexLoop[{B}].Grid1[{_3}].rating");
See also
Data Management functions
FlipGrid
Retrieves flipped data from SourceGrid. SourceGrid contains the originally collected data; DestinationGrid (used for OnNextCase events) stores the flipped data.
Syntax
FlipGrid(SourceGrid, DestinationGrid, QuestionNameForFlip,IterationFilter)
Parameters
SourceGrid
Type: Object
Grid question
DestinationGrid
Type: Object
Grid question
QuestionNameForFlip
Type: Text
The categorical question name for being flipped (optional).
IterationFilter
Type: None
Categorical for iteration filter. The default is NULL.
(return)
Type: Boolean
True if the flip is successful.
Notes
There are restrictions when using this function:
▪When DestinationGrid is a categorical loop with only one nested categorical question, and SourceGrid is a categorical loop, which might have more than one question but has at least one categorical question, the flipping only occurs for the categorical question QuestionNameForFlip. If the question name QuestionNameForFlip is not specified, the flip occurs for the first nested categorical question.
▪There might be some iteration categories for DestinationGrid that do not exist in the question categories for sub-questions in SourceGrid, or there might be some question categories in the sub-questions for DestinationGrid that do not exist in the iteration categories for SourceGrid. This function only flips for:
▪The common categories between the DestinationGrid sub-question categories and the SourceGrid iteration categories.
▪The common categories between the DestinationGrid iteration categories and SourceGrid sub-question categories.
If the DestinationGrid sub-question response values are null after being flipped, they are assigned to the NA category (if the question has one) unless all values, for the question being flipped in a source loop, are null in the current data row.
Example
FlipGrid(myTestLoop, MyFlipLoop, "Grid", null)
The definitions for myTestLoop and MyFlipLoop are as follows:
MyTestLoop "For the following products,please indicate your opinion?" loop
{
A "Product A",
B "Product B",
C "Product C",
D "Product D"
} fields -
(
Grid "Preference" categorical [1..1]
{
Like "Like",
LikeABit -,
Dislike "Dislike",
SourceNa - NA
};

) expand grid;

MyFlipLoop - loop
{
Like -,
LikeABit -,
Dislike -
} fields -
(
Type "Type" categorical [1..]
{
A -,
B -,
C -,
D -
};

) expand grid;
For the current record, the value for MyTestLoop is as follows:
LevelID
Grid
{A}
{ Dislike }
{B}
{Like}
{C}
{LikeABit}
{D}
{ LikeABit }
The value for MyFlipLoop is as follows:
LevelID
Type
{ Like }
{ B }
{ Dislike }
{A}
{ LikeABit }
{C,D}
FlipGrid(myTestLoop, MyFlipLoop, "Grid", {Like,Dislike})
The value for MyFlipLoop is as follows:
LevelID
Type
{ Like }
{ B }
{ Dislike }
{A}
See also
Data Management functions
RemoveCategory
Removes the deprecated OldCategory from MDMObject (often used in the OnJobEnd event).
Syntax
RemoveCategory(MDMObject, QuestionName, OldCategory)
Parameters
MDMObject
Type: object
The name for the MDM document that contains QuestionName.
QuestionName
Type: string
The name of the question object from which oldCategory will be removed.
OldCategory
Type: string
The category item being moved from QuestionName.
(return)
Type: Boolean
Returns True if moving oldCategory is successful, otherwise returns False.
Notes
The category OldCategory might exist in defined categories for categorical questions, iteration categorical, or defined question categories for loop questions.
There are restrictions when using this function:
▪The QuestionName question type is categorical, loop numeric, or loop categorical.
Example 1
RemoveCategory(mdmObject, "cat", "tiger")
Before removing
After removing
cat - categorical [1..]
{
Dog -,
Goldfish -,
Panda -,
Giraffe -,
Tiger -,
DonKnow -
};
cat - categorical [1..]
{
Dog -,
Goldfish -,
Panda -,
Giraffe -,
DonKnow -

};
RemoveCategory(mdmObject, "MyLoopCatQuestion", "tiger")
Example 2
The following table illustrates changes after running this example:
Before removing
After removing
MyLoopCatQuestion - loop
{
A "A",
B "B",
C "C",
D "D"
} fields -
(
rating "rating"
categorical [1..1]
{
Dog "Dog",
Goldfish "Goldfish",
Tiger "Tiger",
Panda "Panda",
Giraffe "Giraffe"
};

) expand grid;
MyLoopCatQuestion - loop
{
A "A",
B "B",
C "C",
D "D"
} fields -
(
rating "rating"
categorical [1..1]
{
Dog "Dog",
Goldfish "Goldfish",
Panda "Panda",
Giraffe "Giraffe"
};

) expand grid;
Example 3
RemoveCategory(mdmObject, "MyLoopLogicQuestion", "snake")
The following table illustrates changes after running this example:
Before removing
After removing
MyLoopLogicQuestion - loop
{
Dog "Dog",
Goldfish "Goldfish",
Panda "Panda",
Giraffe "Giraffe",
Tiger "tiger"
} fields -
(
YesOrNo categorical [1..1]
{
Yes "Yes",
No "No"
};

) expand grid;
MyLoopLogicQuestion - loop
{
Dog "Dog",
Goldfish "Goldfish",
Panda "Panda",
Giraffe "Giraffe"

} fields -
(
YesOrNo categorical [1..1]
{
Yes "Yes",
No "No"
};

) expand grid;
See also
Data Management functions
ReplaceCategory
Replaces oldCategory with newCategory for a loop/categorical questions (used for OnNextCase events).
Syntax
ReplaceCategory(Question, oldCategory, newCategory)
Parameters
Question
Type: object
Category question or loop question.
oldCategory
Type: string
Category item that will be replaced with newCategory.
newCategory
Type: string
The new category value that replaces oldCategory.
(return)
Type: Boolean
True when oldCategory successfully replaces newCategory, otherwise False
Notes
For each question, the oldCategory can be an iteration category, a question category for a loop question, or a category for categorical question.
There are restrictions when using this function:
▪When the question is a category question, oldCategory and newCategory are the defined categories.
▪When the question is a loop question, oldCategory can be in the iteration categories or in the defined category items for the nested question.
Example
The definitions for cat, MyLoopCatQuestion, and MyLoopLogicQuestion are as follows:
cat "What animal you like?"categorical [1..]
{
Dog "Dog",
Goldfish "Goldfish",
Panda "Panda",
Giraffe "Giraffe",
snake "snake",
dontKnow "dontKnow",
Serpent "Serpent"
};

MyLoopCatQuestion - loop
{
A "A",
B "B",
C "C",
D "D"
} fields -
(
rating categorical [1..1]
{
Dog "Dog",
Goldfish "Goldfish",
Panda "Panda",
Giraffe "Giraffe",
snake "snake",
Serpent " Serpent "
};

) expand grid;

MyLoopLogicQuestion - loop
{
Dog "Dog",
Goldfish "Goldfish",
Panda "Panda",
Giraffe "Giraffe",
snake "snake",
Serpent " Serpent "
} fields -
(
YesOrNo categorical [1..1]
{
Yes "Yes",
No "No"
};

) expand grid;
ReplaceCategory(cat, "snake", "Serpent")
The related response.value for the question cat is as follows:
Before replacement
After replacement
{dog,snake,panda}
{ dog,serpent,panda }
{giraffe,snake}
{giraffe,serpent}
{dog,goldfish}
{dog,goldfish}
ReplaceCategory(MyLoopCatQuestion, "snake", "Serpent")
The related response.value for the question MyLoopCatQuestion is as follows:
Question
Before replacement
After replacement
MyLoopCatQuestion[{A}].Rating
{dog,snake,panda}
{ dog,serpent,panda }
MyLoopCatQuestion[{B}].Rating
{giraffe,snake}
{giraffe,serpent}
MyLoopCatQuestion[{C}].Rating
{dog,goldfish}
{dog,goldfish}
MyLoopCatQuestion[{D}].Rating
{snake}
{serpent}
ReplaceCategory(MyLoopLogicQuestion, "snake", "Serpent")
After running the function, the value of all sub-questions for iteration snake are copied for iteration serpent.
See
SubtractQuestion
SumQuestions
Data Management reference