Value resolution

Most of the functions in the Function Library operate on a data value of one of the UNICOM Intelligence Data Model data types of Boolean, Long, Double, Text, Categorical, Date, or Object. When more than one type of value is allowed, the parameter is declared as type None, and an error occurs if the value supplied is of an inappropriate type.

Value parameters to functions can be literal values (such as, 7.5, "Yes" or {1,6,7}), expressions of the appropriate type, or the names of variables. When a variable name is given in a function call in which a value is expected, the current value of the variable is used.

Categorical values can be expressed in these different ways:

▪Using the numeric category values only: for example, {1,6,7}. These can be passed to any function that expects a categorical value.

▪Using one of the Category expressions, which is a string that is a type of regular expression that selects ranges of categories and/or negated (excluded) categories. For example, "Tea .. Coffee, ^Chocolate .. Fruit."

Because category expressions are strings, they can be used only for parameters that can accept values of type Text as well as type Categorical. These parameters are shown as type None. A parameter that accepts only a categorical type cannot accept category expressions.

When category names or expressions are passed to a parameter, the Function Library component requires an MDM document to be able to convert the names or expression to a list of category numbers, which it then passes to the function. Therefore, you can pass category names or a category expression to a parameter only when the case data is opened with an MDM document, or when a script has an open MDM document available to it.

Categorical literals (categories enclosed by {}) are evaluated at parse time. Categorical expressions, supplied as string literals (enclosed by "") are evaluated at run time. Given that the categories for a database question are only known at run time, after connecting to the database, the categorical values for database questions must be supplied as categorical expressions (string literals enclosed by "").

For more information on the benefits of using categorical literals, see Data Management performance guidelines white paper.

Functions that are passed categorical values that contain category names or a category expression must be able to reference an open MDM document, which can be in the form of an MDM document stored in a .mdd file or an MDM document generated from proprietary metadata by a read-enabled MDSC. If an open MDM document is not available, the categorical value passed to the function must consist only of category numbers, otherwise an error will occur.

In a mrScriptBasic script, you typically specify an open MDM document in one of two ways:

▪By using the CreateObject function to create and return a reference to an MDM document object, and then using the object's Open method to open an MDM document stored in a .mdd file. For example, the following mrScriptBasic example opens the museum.mdd sample file for read-only access. The document is then accessible to functions by using the MyDocument variable.

Dim MyDocument
Set MyDocument = CreateObject("MDM.Document")
MyDocument.Open("[INSTALL_FOLDER]\IBM\SPSS\DataCollection\7\DDL\Data\Data Collection File\ museum.mdd", , _
MDMLib.openConstants.oREAD)

[INSTALL_FOLDER] is the directory where you installed UNICOM Intelligence, such as C:\Program Files:

▪To open an MDM document in read-only mode, use the /m: option of the mrScript Command Line Runner. The document is then accessible to functions by using an intrinsic variable called MDM.

In a Data Management Script (DMS) file, the MDM document specified in the InputDataSource section is automatically available as an open document in the OnJobStart, OnAfterMetaDataTransformation, OnNextCase, OnBadCase, and OnJobEnd event sections of the script.